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 Actions SDK

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

Önemli: Inline Cloud Functions düzenleyicisiyle karşılama oluşturup dağıtıyorsanız Google Cloud'daki projenize bir faturalandırma hesabı bağlamanız gerekir. Bu koşul, 17 Ağustos 2020'den itibaren geçerli olacaktır. Google Cloud'da bir faturalandırma hesabını projenize bağlama talimatları için Proje faturalandırma ayarlarını değiştirme başlıklı makaleyi inceleyin. Daha fazla bilgi için Kotalar ve Fiyatlandırma bölümlerine bakın. Hizmet kesintilerini önlemek için en kısa sürede bir faturalandırma hesabı ilişkilendirmenizi önemle tavsiye ederiz.

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

1. sdk/webhooks/ActionsOnGoogleFulfillment.yaml dosyasını oluşturun ve İşleminiz ile karşılama için kullanılan satır içi Cloud Functions işlevinin işleyicilerini tanımlayın.

   handlers:
   - name: questionOnEnterFunc
   - name: fruitSlotValidationFunc
   inlineCloudFunction:
     executeFunction: ActionsOnGoogleFulfillment
       

2. sdk/webhooks/ActionsOnGoogleFulfillment klasörünü oluşturun, önceden tanımlanmış işleyicileri uygulayan bir index.js dosyası ve kodunuz için npm gereksinimlerini tanımlayan bir package.json dosyası ekleyin.

   // 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, 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.

Önemli: Firebase için Cloud Functions ile karşılama oluşturup dağıtıyorsanız Google Cloud'da projenize bir faturalandırma hesabı bağlamanız gerekir. Bu koşul, 17 Ağustos 2020'den itibaren geçerli olacaktır. Google Cloud'da bir faturalandırma hesabını projenize bağlama talimatları için Proje faturalandırma ayarlarını değiştirme başlıklı makaleyi inceleyin. Daha fazla bilgi için Kotalar ve Fiyatlandırma bölümlerine bakın. Hizmet kesintilerini önlemek için en kısa sürede bir faturalandırma hesabı ilişkilendirmenizi önemle tavsiye ederiz.

Ortamı ayarlama

Firebase için Cloud Functions'ı karşılama hizmeti olarak kullanırken aşağıdaki proje yapısını öneririz:

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

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:

   Not: [don't setup a default project] (varsayılan proje oluşturma) seçeneğini belirleyerek bu adımı atlayabilirsiniz. Ancak daha sonra firebase use PROJECT_ID komutunu kullanarak bu ilişkilendirmeyi yapmanız gerekir.

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

1. sdk/webhooks/ActionsOnGoogleFulfillment.yaml dosyasını oluşturun ve İşleminiz için işleyicileri ve webhook isteklerinin URL'sini tanımlayın.

   httpsEndpoint:
     baseUrl: https://my.web.hook/ActionsOnGoogleFulfillment
     endpointApiVersion: 2
   handlers:
   - name: questionOnEnterFunc
   - name: fruitSlotValidationFunc