Actions oluşturma sırasında size daha da fazla esneklik sağlamak için HTTPS web hizmetlerine (sipariş karşılama) mantık yetkisi verebilirsiniz. İşlemleriniz bir HTTPS uç noktasına istek gönderen webhook'ları tetikleyebilir. Bu şartları yerine getirmek için yapabileceklerinizden bazıları şunlardır:
- Kullanıcı tarafından sağlanan bilgilere dayalı dinamik istem oluşturma.
- Harici bir sistemde sipariş verme ve bunu onaylama.
- Yuvaları arka uç verileriyle doğrulama.
Webhook tetikleyicileri ve işleyicileri
İşlemleriniz, çağrı amaçları veya sahneleri içinde bir webhook'u tetikleyebilir. Bu yöntem, istek karşılama uç noktanıza istek gönderir. İstek karşılama mantığınız, istekteki JSON yükünü işleyen webhook işleyicileri içeriyor. Webhook'ları aşağıdaki durumlarda tetikleyebilirsiniz:
- Bir çağrı amacı eşleşmesinden sonra
- Bir sahneye giriş sırasında
- Bir düzenin koşul aşamasında bir koşul doğru olarak değerlendirildikten sonra
- Bir sahnenin slot doldurma aşamasında
- Sahnenin giriş aşamasında intent eşleşmesi gerçekleştikten sonra
Actions'ınızda bir webhook'u tetiklediğinizde Google Asistan, karşılama etkinliğinize bir JSON yükü içeren istek gönderir. Bu istek, etkinliği işlemek için kullanılacak işleyicinin adını içerir. İstek karşılama uç noktanız, mantığı gerçekleştirmek ve JSON yükü ile buna karşılık gelen bir yanıt döndürmek için etkinliği uygun işleyiciye yönlendirebilir.
Yükler
Aşağıdaki snippet'lerde, işlemlerinizin istek karşılamaya gönderdiği örnek istekler ve karşılamanızın geri gönderdiği bir yanıt gösterilmektedir. Daha fazla bilgi edinmek için referans belgelerine göz atın.
Ö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, webhook işleyicilerinizde gerçekleştirebileceğiniz genel görevler açıklanmaktadır.
İstem gönder
Etkileşimli Tuval ile basit metin, zengin metin, kart ve web uygulaması tarafından desteklenen tam gelişmiş HTML istemleri içeren istemler oluşturabilirsiniz. Bir webhook etkinliğini işlerken istem oluşturma hakkında tüm bilgileri istemler belgesinde bulabilirsiniz. Aşağıdaki snippet'lerde bir kart istemi gösterilmektedir:
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 niyetle eşleştiğinde, tanımlanan tüm parametreleri çıkarır. Orijinal özellik, kullanıcının giriş olarak sağladığı özellikti ve çözümlenen özellik, NLU'nun tür spesifikasyonuna göre girişi çözümlediği özellikti.
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 için 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"
]
}
}
Depolama alanını okuma ve yazma
Çeşitli depolama alanı özelliklerinin nasıl kullanılacağı hakkında ayrıntılı bilgi için depolama belgelerine bakın.
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 edin
Farklı deneyimler veya görüşme akışları sunmak için cihazın özelliklerini kontrol edebilirsiniz.
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"
]
}
}
Platform özelliklerinin tam listesi için Capability referansına bakın.
Çalışma zamanı türü geçersiz kılmaları
Çalışma zamanı türleri, çalışma zamanında tür özelliklerini değiştirmenizi sağlar. Bir türün geçerli değerlerini doldurmak amacıyla diğer kaynaklardan veri yüklemek için bu özelliği kullanabilirsiniz. Örneğin, bir anket sorusuna dinamik seçenekler veya menüye günlük bir öğe eklemek için çalışma zamanı türü geçersiz kılmalarını kullanabilirsiniz.
Çalışma zamanı türlerini kullanmak için İşleminizden, istek karşılamanızdaki bir işleyiciyi çağıran bir webhook'u tetiklersiniz. Buradan, İşleminize verilen yanıtta session.typeOverrides parametresini doldurabilirsiniz. Kullanılabilir modlar, mevcut tür girişlerini korumak için TYPE_MERGE veya mevcut girişleri geçersiz kılmalarla değiştirmek için TYPE_REPLACE içerir.
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 yönelik ipuçları belirtebilmenizi sağlar. En fazla 1.000 giriş belirtebilirsiniz.
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ımlamanın yanı sıra çalışma zamanında sahne geçişlerinin gerçekleşmesine de neden olabilirsiniz.
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ı oku
Slot doldurma sırasında, yuvayı doğrulamak veya slot doldurma durumunu (SlotFillingStatus) kontrol etmek için istek karşılama özelliğini kullanabilirsiniz.
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. Bu örnekte, alan adı datetime1'dir. Saat dilimini öğrenmek için şunları kullanmanız gerekir:
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ın
Slotları geçersiz kılabilir ve kullanıcının yeni bir değer sağlamasını 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, doğrudan konsolda Firebase için Cloud Functions işlevi oluşturup dağıtmanıza olanak tanıyan Cloud Functions düzenleyicisi adlı bir satır içi düzenleyici sunar. Ayrıca, istek karşılama oluşturup istediğiniz barındırma sitesine dağıtabilir ve HTTPS karşılama uç noktanızı webhook işleyiciniz olarak kaydedebilirsiniz.
Satır içi düzenleyici
Cloud Functions düzenleyiciyle geliştirmek için:
- Actions projenizi açın ve Geliştirme sekmesi > Webhook > İstek karşılama yöntemini değiştir'e gidin. Karşılama yöntemleri penceresi görünür.
- Satır İçi Cloud Functions'ı seçin ve Onayla'yı tıklayın.
Harici HTTPS uç noktası
Bu bölümde, Conversational Action'ınız için bir karşılama hizmeti olarak Cloud Functions for Firebase'i nasıl ayarlayacağınız açıklanmaktadır. Ancak istek karşılamayı istediğiniz bir barındırma hizmetine dağıtabilirsiniz.
Ortamı ayarlama
Ortamınızı ayarlamak için aşağıdaki adımları uygulayın:
- Node.js'yi indirip yükleyin.
Firebase CLI'yi ayarlayıp başlatın. Aşağıdaki komut
EACCEShatasıyla başarısız olursa npm izinlerini değiştirmeniz gerekebilir.npm install -g firebase-toolsFirebase aracının kimliğini Google hesabınızla doğrulayın:
firebase loginActions projenizi kaydettiğiniz proje dizinini başlatın. Actions projeniz için hangi Firebase CLI özelliklerini ayarlamak istediğinizi seçmeniz istenir.
Functionshizmetini ve kullanmak isteyebileceğiniz diğer özellikleri (ör. Firestore) seçin ve onaylamak ve devam etmek için Enter tuşuna basın:$ cd <ACTIONS_PROJECT_DIRECTORY> $ firebase initProje listesinde gezinmek için ok tuşlarını kullanıp Firebase aracını seçerek projenizle ilişkilendirin:
Projeyi seçtikten sonra Firebase aracı, Functions kurulumunu başlatır ve 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
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)
İ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 aşağıdakine benzer bir çıkış görürsünüz:
✔ Firebase initialization complete!@assistant/conversation bağımlılığını yükleyin:
$ cd <ACTIONS_PROJECT_DIRECTORY>/functions $ npm install @assistant/conversation --saveİstek karşılama bağımlılıklarını alın ve istek karşılama işlevini dağıtın:
$ npm install $ firebase deploy --only functionsDağıtım birkaç dakika sürer. İşlem tamamlandığında aşağıdakine benzer bir çıkış görürsünüz. Dialogflow'a girmek için İşlev URL'sine ihtiyacınız olacaktır.
✔ 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>Sonraki bölümde kullanılacak istek karşılama URL'sini kopyalayın.
Webhook işleyiciyi kaydet
Cloud Functions uç noktanızı webhook işleyici olarak kaydetmek için:
- Actions konsolunda Geliştir > Webhook'u tıklayın.
- Sipariş karşılama yöntemini değiştir'i tıklayın. Karşılama yöntemleri penceresi açılır.
- Webhook'u seçin ve Onayla'yı tıklayın.
- Web hizmeti URL'nizi Webhook alanına yapıştırın.
- Kaydet'i tıklayın.