Webhook'lar

İşlemler oluşturma konusunda daha fazla esneklik sağlamak için kullanıcılara HTTPS web hizmetlerine geçirme (sipariş karşılama). İşlemleriniz, şu özelliklere sahip webhook'ları tetikleyebilir: HTTPS uç noktasına istek yapar. Bu programda yapabileceklerinize sipariş karşılama şunları içerir:

  • Kullanıcının sağladığı bilgilere göre dinamik istem oluşturma.
  • Harici bir sisteme sipariş verme ve işlemin başarılı olduğunu onaylama.
  • Arka uç verileriyle alanlar doğrulanıyor.
ziyaret edin.
Şekil 1. Çağrı amaçları ve sahneleri tetiklenebilir web kancaları gibi).

Webhook tetikleyicileri ve işleyicileri

İşlemleriniz çağrı amaçları veya sahneler içinde bir webhook'u tetikleyebilir. sipariş karşılama uç noktanıza bir istek gönderir. Sipariş karşılama işleminiz webhook içeriyor işleyiciler tarafından yapılandırılabilir. Webhook'ları tetikleyebilirsiniz. aşağıdaki durumlarda:

  • Çağrı amacı eşleşmesinden sonra
  • Bir sahnenin giriş sahnesinde
  • Bir sahnenin koşul aşamasında bir koşul doğru olarak değerlendirildikten sonra
  • Bir sahnenin yuvayı doldurma aşamasında
  • Bir sahnenin giriş aşamasında intent eşleşmesi gerçekleştikten sonra

Actions'larınızda bir webhook'u tetiklediğinizde Google Asistan bir istek gönderir. bir JSON yüküyle ekleyebilirsiniz. Bu örnek, etkinliği işlemek için kullanılacak işleyicinin adıdır. Sipariş karşılama uç noktanız: mantığı yürütmek ve bir JSON yüküyle karşılık gelen yanıt oluşturabilirsiniz.

Yükler

Aşağıdaki snippet'lerde, Actions'ınızın gönderdiği örnek istekler gösterilmektedir ve sipariş karşılamanın geri gönderdiği bir yanıttır. Bkz. Daha fazla bilgi için referans belgeleri ekleyebilirsiniz.

Örnek İstek

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Örnek yanıt

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello World.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

Çalışma zamanı etkileşimleri

Aşağıdaki bölümlerde, günlük işinizde yapabileceğiniz genel görevler webhook işleyicileri ekleyin.

İstem gönderin

Basit metinler, zengin metin ve kartlarla istem oluşturabilir, hatta videonun tamamını oynatabilirsiniz. Etkileşimli Tuval içeren web uygulaması tarafından desteklenen HTML istemleri. prompts dokümanlarında webhook etkinliği işlenirken istem oluşturma hakkında eksiksiz bilgi. Aşağıdaki snippet'lerde bir kart istemi gösterilir:

Node.js

app.handle('rich_response', conv => {
  conv.add('This is a card rich response.');
  conv.add(new Card({
    title: 'Card Title',
    subtitle: 'Card Subtitle',
    text: 'Card Content',
    image: new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    })
  }));
});

Yanıt JSON

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "content": {
      "card": {
        "title": "Card Title",
        "subtitle": "Card Subtitle",
        "text": "Card Content",
        "image": {
          "alt": "Google Assistant logo",
          "height": 0,
          "url": "https://developers.google.com/assistant/assistant_96.png",
          "width": 0
        }
      }
    },
    "firstSimple": {
      "speech": "This is a card rich response.",
      "text": ""
    }
  }
}

Amaç parametrelerini okuma

Asistan çalışma zamanı bir intentle eşleştiğinde tanımlanmış tüm parametreleridir. Orijinal özellik, kullanıcının girdi olarak sağladığı ve çözümlenen özellik, NLU'nun türe göre girişi çözümlediği değerdir bakın.

Node.js

conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved

JSON isteğinde bulun

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "intent_name",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Kullanıcı yerel ayarını okuma

Bu değer, kullanıcının Google Asistan'daki yerel ayarına karşılık gelir.

Node.js

conv.user.locale

JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Okuma ve yazma depolama alanı

çeşitli depolama özellikleri kullanır.

Node.js

//read
conv.session.params.key
conv.user.params.key
conv.home.params.key

// write
conv.session.params.key = value
conv.user.params.key = value
conv.home.params.key = value

JSON isteğinde bulun

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    },
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Yanıt JSON

{
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello world.",
      "text": ""
    }
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  }
}

Cihaz özelliklerini kontrol etme

Farklı deneyimler sunmak veya konuşmanın akışını sağlar.

Node.js

const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsLongFormAudio = conv.device.capabilities.includes("LONG_FORM_AUDIO");
const supportsSpeech = conv.device.capabilities.includes("SPEECH");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");

JSON isteğinde bulun

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO",
      "INTERACTIVE_CANVAS"
    ]
  }
}

Yüzey özelliklerinin tam listesi için bkz. Capability bir referans noktası olarak kabul edilir.

Çalışma zamanı türü geçersiz kılmaları

Çalışma zamanı türleri, çalışma zamanında tür özelliklerini değiştirmenize olanak tanır. Bunu kullanabilirsiniz özelliğini kullanın. Örneğin, Örneğin, bir ankete dinamik seçenekler eklemek için çalışma zamanı türü geçersiz kılmalarını veya menüye günlük bir öğe eklemek için yeterli olmayabilir.

Çalışma zamanı türlerini kullanmak için İşleminizden işleyicisi ile karşı karşıyasınız. Burada, İşleminize yanıt olarak session.typeOverrides parametresi eklemeniz gerekir. Uygun modlar, mevcut tür girişlerini korumak için TYPE_MERGE veya TYPE_REPLACE içerir kullanabilirsiniz.

Node.js

conv.session.typeOverrides = [{
    name: type_name,
    mode: 'TYPE_REPLACE',
    synonym: {
      entries: [
        {
          name: 'ITEM_1',
          synonyms: ['Item 1', 'First item']
        },
        {
          name: 'ITEM_2',
          synonyms: ['Item 2', 'Second item']
       },
       {
          name: 'ITEM_3',
          synonyms: ['Item 3', 'Third item']
        },
        {
          name: 'ITEM_4',
          synonyms: ['Item 4', 'Fourth item']
        },
    ]
  }
}];

Yanıt JSON

{
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [
      {
        "name": "type_name",
        "synonym": {
          "entries": [
            {
              "name": "ITEM_1",
              "synonyms": [
                "Item 1",
                "First item"
              ]
            },
            {
              "name": "ITEM_2",
              "synonyms": [
                "Item 2",
                "Second item"
              ]
            },
            {
              "name": "ITEM_3",
              "synonyms": [
                "Item 3",
                "Third item"
              ]
            },
            {
              "name": "ITEM_4",
              "synonyms": [
                "Item 4",
                "Fourth item"
              ]
            }
          ]
        },
        "typeOverrideMode": "TYPE_REPLACE"
      }
    ]
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  }
}

Konuşmaya ağırlık verme

Konuşmaya ağırlık verme, intent eşleşmesini iyileştirmek için NLU'ya (nLU) ipuçları vermenizi sağlar. Siz en fazla 1.000 giriş belirtebilir.

Node.js

conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'

Yanıt JSON

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  },
  "expected": {
    "speech": "['value_1', 'value_2']",
    "language": "locale_string"
  }
}

Geçiş sahneleri

Actions projenizde statik geçişler tanımlamaya ek olarak, sahne geçişlerinin gerçekleşmesine neden olur.

Node.js

app.handle('transition_to_hidden_scene', conv => {
  // Dynamic transition
  conv.scene.next.name = "HiddenScene";
});

Yanıt JSON

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "HiddenScene"
    }
  }
}

Sahne aralıklarını okuma

Alan doldurma sırasında, aralığı doğrulamak veya zaman aralığı doldurmanın durumu (SlotFillingStatus).

Node.js

conv.scene.slotFillingStatus  // FINAL means all slots are filled
conv.scene.slots  // Object that contains all the slots
conv.scene.slots['slot_name'].<property_name> // Accessing a specific slot's properties

Örneğin, bir yanıtın saat dilimini çıkarmak istediğinizi varsayalım. İçinde Bu örnekte, alan adı datetime1 şeklindedir. Saat dilimini almak için, kullanın:

conv.scene.slots['datetime1'].value.time_zone.id

JSON isteğinde bulun

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "FINAL",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "SLOT_UNSPECIFIED",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    },
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Sahne aralıklarını geçersiz kıl

Alanları geçersiz kılabilir ve kullanıcının yeni bir değer girmesini sağlayabilirsiniz.

Node.js

conv.scene.slots['slot_name'].status = 'INVALID'

Yanıt JSON

{
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "INVALID",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

Geliştirme seçenekleri

Actions Builder, Cloud Functions düzenleyicisi olarak adlandırılan bir satır içi düzenleyici sunar. Bu, Firebase için Cloud Functions işlevini doğrudan konsolu. Ayrıca, sipariş karşılama oluşturabilir ve tercih ettiğiniz barındırma türüne dağıtabilirsiniz ve HTTPS karşılama uç noktanızı webhook işleyiciniz olarak kaydedin.

Satır içi düzenleyici

Cloud Functions düzenleyicisiyle geliştirme yapmak için:

  1. sdk/webhooks/ActionsOnGoogleFulfillment.yaml dosyasını oluşturun. İşleminiz ve kullanılan satır içi bulut işlevi için işleyicileri tanımlayın göz önünde bulundurmalısınız. 
    handlers:
- name: questionOnEnterFunc
- name: fruitSlotValidationFunc
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment
  2. sdk/webhooks/ActionsOnGoogleFulfillment klasörünü oluşturun. ve işleyicileri uygulayan bir index.js dosyası ekleyin önceden tanımlanmış ve npm'yi tanımlayan bir package.json dosyası veya kodunuzla ilgili tüm gereksinimleri karşılayın. 
    // index.js
const {conversation} = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation();

app.handle('questionOnEnterFunc', conv => {
  conv.add('questionOnEnterFunc triggered on webhook');
});

app.handle('fruitSlotValidationFunc', conv => {
  conv.add('fruitSlotValidationFunc triggered on webhook');
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);
    
    // package.json
{
  "name": "ActionsOnGoogleFulfillment",
  "version": "0.1.0",
  "description": "Actions on Google fulfillment",
  "main": "index.js",
  "dependencies": {
    "@assistant/conversation": "^3.0.0",
    "firebase-admin": "^5.4.3",
    "firebase-functions": "^0.7.1"
  }
}

Harici HTTPS uç noktası

Bu bölümde, Firebase için Cloud Functions'ı Conversational Action'ın sipariş karşılama hizmeti Ancak isterseniz bir barındırma hizmetine sipariş karşılama.

Ortamı ayarlama

Cloud Functions işlevlerini şunlar için kullandığınızda aşağıdaki proje yapısını öneririz: Sipariş karşılama hizmeti olarak Firebase:

ProjectFolder        - Root folder for the project
  sdk                - Actions project configuration files
  functions          - Cloud functions for Firebase files

Ortamınızı ayarlamak için şu adımları uygulayın:

  1. Node.js'yi indirip yükleyin.

  2. Firebase CLI'yı kurun ve başlatın. Aşağıdaki komut EACCES hatası veriyorsa npm izinlerini değiştirmeniz gerekebilir.

    npm install -g firebase-tools

  3. Firebase aracını Google hesabınızla doğrulayın:

    firebase login

  4. Actions projenizi kaydettiğiniz proje dizinini başlatın. Hangi Firebase CLI özelliklerini ayarlamak istediğiniz sorulur. eyleme dökülebilir. Functions özelliğini ve isteyebileceğiniz diğer özellikleri seçin kullanın, ardından onaylamak ve devam etmek için Enter tuşuna basın:

    $ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init

  5. Firebase aracını Eylemler projenizle ilişkilendirmek için proje listesinde gezinmek için ok tuşlarını kullanın:

  6. Proje seçildikten sonra Firebase aracı, İşlevler'i başlatır size hangi dili kullanmak istediğinizi sorar. Ok tuşlarını kullanarak seçin ve devam etmek için Enter tuşuna basın.

    === Functions Setup
A functions directory will be created in your project with a Node.js
package pre-configured. Functions can be deployed with firebase deploy.

? What language would you like to use to write Cloud Functions? (Use arrow keys)
> JavaScript
TypeScript

  7. Olası hataları yakalamak ve Y ya da N yazarak stili uygulamak için ESLint'i kullanmak isteyip istemediğinizi seçin:

    ? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)

  8. İsteme Y yazarak proje bağımlılıklarını alın:

    ? Do you want to install dependencies with npm now? (Y/n)

    Kurulum tamamlandıktan sonra şuna benzer bir çıkış görürsünüz:

    ✔  Firebase initialization complete!

  9. @assistant/conversation bağımlılığını yükleyin:

    $ cd <ACTIONS_PROJECT_DIRECTORY>/functions
$ npm install @assistant/conversation --save

  10. Sipariş karşılama bağımlılıklarını alın ve karşılama işlevini dağıtın:

    $ npm install
$ firebase deploy --only functions

    Dağıtım birkaç dakika sürer. İşlem tamamlandığında şuna benzer bir çıkış görürsünüz: şunlar olabilir: Dialogflow'a girebilmek için İşlev URL'si gereklidir.

    ✔  Deploy complete!
    
Project Console: https://console.firebase.google.com/project/<PROJECT_ID>/overview
Function URL (<FUNCTION_NAME>): https://us-central1-<PROJECT_ID>.cloudfunctions.net/<FUNCTION_NAME>

  11. Sonraki bölümde kullanılacak sipariş karşılama URL'sini kopyalayın.

Webhook işleyiciyi kaydedin

  1. sdk/webhooks/ActionsOnGoogleFulfillment.yaml dosyasını oluşturun ve tanımlayın İşleminizin işleyicilerini ve webhook isteklerinin URL'sini ekleyin. 
    httpsEndpoint:
  baseUrl: https://my.web.hook/ActionsOnGoogleFulfillment
  endpointApiVersion: 2
handlers:
- name: questionOnEnterFunc
- name: fruitSlotValidationFunc