Webhook'lar

İşlemleri oluştururken daha da fazla esneklik sağlamak için mantığı HTTPS web hizmetlerine (karşılama) devredebilirsiniz. İşlemleriniz, HTTPS uç noktasına istek gönderen webhook'ları tetikleyebilir. Karşılama sürecinde yapabileceklerinizden bazıları şunlardır:

  • Kullanıcı tarafından sağlanan bilgilere göre dinamik bir istem oluşturma
  • Harici bir sistemde sipariş verme ve işlemin başarılı olduğunu onaylama.
  • Arka uç verileriyle yuvaları doğrulama.
Şekil 1. Çağırma amaçları ve sahneleri webhook'ları tetikleyebilir.

Webhook tetikleyicileri ve işleyicileri

İşlemleriniz, istek karşılama uç noktanıza istek gönderen, çağırma niyetleri veya sahnelerindeki bir webhook'u tetikleyebilir. Karşılama işleminiz, istekteki JSON yükünü işleyen webhook işleyiciler içeriyor. Aşağıdaki durumlarda webhook'ları tetikleyebilirsiniz:

  • Çağırma amacı eşleştirmesinden sonra
  • Bir sahnenin sahneye giriş aşamasında
  • Bir sahnenin koşul aşamasında bir koşul doğru olarak değerlendirildikten sonra
  • Bir sahnenin yuva doldurma aşamasında
  • Bir sahnenin giriş aşamasında amaç eşleşmesi gerçekleştikten sonra

İşlemlerinizde bir webhook tetiklediğinizde Google Asistan, karşılamanıza JSON yükü içeren bir 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ığı yürütmek ve JSON yükü içeren 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, İşlemlerinizin karşılama işlemine gönderdiği örnek istekler ve karşılama işleminizin geri gönderdiği yanıt gösterilmektedir. Daha fazla bilgi 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 yaygın görevler açıklanmaktadır.

İstem gönderme

Basit metin, zengin metin, kartlar ve hatta Etkileşimli Canvas'ı destekleyen bir web uygulamasıyla tam teşekküllü HTML istemleri içeren istemler oluşturabilirsiniz. İstemler dokümanında, webhook etkinliği işlenirken istem oluşturma hakkında eksiksiz bilgiler yer almaktadır. Aşağıdaki snippet'lerde 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'u

{
  "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": ""
    }
  }
}

Okuma amacı parametreleri

Asistan çalışma zamanı bir amaçla eşleştiğinde tanımlanan tüm parametreleri ayıklar. Orijinal özellik, kullanıcının giriş olarak sağladığı özelliktir. Çözümlenen özellik ise NLU'nun, tür spesifikasyonuna göre girişi çözdüğü özelliktir.

Node.js

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

JSON isteği

{
  "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ını ifade eder.

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 özelliklerini kullanma hakkında eksiksiz 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ği

{
  "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'u

{
  "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

Bir cihazın farklı deneyimler veya görüşme akışları sunma ö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ği

{
  "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 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 spesifikasyonlarını değiştirmenize olanak tanır. Bu özelliği, bir türün geçerli değerlerini doldurmak için diğer kaynaklardaki verileri yüklemek üzere kullanabilirsiniz. Örneğin, bir anket sorusuna dinamik seçenekler eklemek veya bir menüye günlük öğe eklemek için çalışma zamanı türü geçersiz kılmaları kullanabilirsiniz.

Çalışma zamanı türlerini kullanmak için Action'ınızdan bir webhook tetikleyerek karşılama işlevinizdeki bir işleyiciyi çağırırsınız. Buradan, İşleminize yanıt olarak session.typeOverrides parametresini doldurabilirsiniz. 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 modları kullanılabilir.

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'u

{
  "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şma önyargısı sağlama

Konuşma önyargısı, NLU'ya ipuçları belirterek amaç eşleşmesini iyileştirmenize olanak tanır. En fazla 1.000 giriş belirtebilirsiniz.

Node.js

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

Yanıt JSON'u

{
  "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"
  }
}

Sahneler arasında geçiş yapma

İşlemler projenizde statik geçişler tanımlamanın yanı sıra çalışma zamanında sahne geçişlerinin gerçekleşmesini de sağlayabilirsiniz.

Node.js

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

Yanıt JSON'u

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

Sahne yuvalarını okuma

Slot doldurma sırasında, slotu doğrulamak veya slot doldurma durumunu (SlotFillingStatus) kontrol etmek için karşılama yanıtını 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ıttan saat dilimini ayıklamak istediğinizi varsayalım. Bu örnekte, alan adı datetime1'dır. Saat dilimini almak için şunları kullanırsınız:

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

JSON isteği

{
  "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 yuvalarını geçersiz kılma

Aralıkları 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'u

{
  "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üzenleyici adlı satır içi bir düzenleyici sunar. Bu düzenleyici, Firebase için Cloud Functions işlevini doğrudan konsolda oluşturup dağıtmanıza olanak tanır. Ayrıca, istediğiniz barındırma hizmetinde karşılama oluşturup dağıtabilir ve HTTPS karşılama uç noktanızı webhook işleyiciniz olarak kaydedebilirsiniz.

Satır içi düzenleyici

Cloud Functions Düzenleyici ile geliştirmek için:

  1. Actions projenizi açın ve Geliştir sekmesi > Web kancası > Yerleştirme yöntemini değiştir'e gidin. Karşılama yöntemleri penceresi görünür.
  2. Satır İçi Bulut İşlevleri'ni seçin ve Onayla'yı tıklayın.

Harici HTTPS uç noktası

Bu bölümde, Cloud Functions for Firebase'i etkileşimli işleminiz için nasıl karşılama hizmeti olarak ayarlayacağınız açıklanmaktadır. Ancak, istediğiniz bir barındırma hizmetine dağıtım yapabilirsiniz.

Ortamı ayarlama

Ortamınızı ayarlamak için aşağıdaki 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ıyla başarısız olursa npm izinlerini değiştirmeniz gerekebilir.

    npm install -g firebase-tools

  3. Firebase aracının kimliğini Google Hesabınızla doğrulayın:

    firebase login

  4. İşlemler projenizi kaydettiğiniz proje dizinini başlatın. İşlemler projeniz için hangi Firebase CLI özelliklerini ayarlamak istediğinizi seçmeniz istenir. Functions ve Firestore gibi kullanmak isteyebileceğiniz diğer özellikleri seçin, ardından onaylamak ve devam etmek için Enter tuşuna basın:

    $ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init

  5. Projeler listesinde gezinmek için ok tuşlarını kullanarak Firebase aracını seçip İşlemler projenizle ilişkilendirin:

  6. 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

  7. Olası hataları yakalamak ve stili zorunlu kılmak için ESLint kullanmak isteyip istemediğinizi Y veya N yazarak seçin:

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

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

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

    Kurulum tamamlandığında aşağıdakine 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. İstek karşılama bağımlılıklarını alın ve istek karşılama işlevini dağıtın:

    $ npm install
$ firebase deploy --only functions

    Dağıtım işlemi birkaç dakika sürer. İşlem tamamlandığında aşağıdakine benzer bir çıkış görürsünüz. Dialogflow'a girmek için Function URL'ye ihtiyacınız vardı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>

  11. Sonraki bölümde kullanmak için karşılama URL'sini kopyalayın.

Webhook işleyicisini kaydetme

Cloud Functions uç noktanızı webhook işleyici olarak kaydetmek için:

  1. Actions konsolunda Geliştir > Web kancası'nı tıklayın.
  2. Karşılanma yöntemini değiştir'i tıklayın. Karşılama yöntemleri penceresi görünür.
  3. Webhook'u seçin ve Onayla'yı tıklayın.
  4. Web hizmeti URL'nizi Webhook alanına yapıştırın.
  5. Kaydet'i tıklayın.