Webhooki

Aby zapewnić jeszcze większą elastyczność tworzenia akcji, możesz przekazać funkcje logiczne do usług internetowych HTTPS (realizacji). Akcje mogą aktywować webhooki, które wysyłania żądań do punktu końcowego HTTPS. Oto co można zrobić w realizacja obejmuje:

  • Generowanie dynamicznego promptu na podstawie informacji podanych przez użytkownika.
  • Złożenie zamówienia w systemie zewnętrznym i potwierdzenie powodzenia
  • Weryfikuję przedziały z danymi backendu.
.
Rysunek 1. Mogą aktywować się intencje i sceny wywołania webhooki.

Wyzwalacze i moduły obsługi webhooka

Akcje mogą aktywować webhooka w ramach intencji lub scen wywołania, które wysyła żądanie do punktu końcowego realizacji. Twoja realizacja zawiera webhooka które przetwarzają ładunek JSON w żądaniu. Możesz aktywować webhooki w tych sytuacjach:

  • Po dopasowaniu intencji wywołania
  • W trakcie sceny
  • Po ocenie stanu jako prawda na etapie stanu sceny
  • Podczas etapu zapełniania przedziałów w scenie
  • Po wystąpieniu dopasowania intencji na etapie wprowadzania sceny

Gdy aktywujesz webhooka w Akcjach, Asystent Google wysyła żądanie: z ładunkiem JSON do realizacji, która zawiera nazwa modułu obsługi, który ma być używany do przetwarzania zdarzenia. Punkt końcowy realizacji zamówień może kierować zdarzenie do odpowiedniego modułu obsługi, aby przeprowadzić logikę i zwrócić błąd odpowiadającej mu odpowiedzi z ładunkiem JSON.

Ładunki

Poniższe fragmenty kodu pokazują przykładowe żądania wysyłane przez akcje do realizację zamówień i odpowiedź odwrotną. Zobacz dokumentacji referencyjnej. i informacjami o nich.

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Interakcje w środowisku wykonawczym

Sekcje poniżej opisują typowe zadania, które można wykonać na modułów obsługi webhooków.

Wysyłaj prompty

Możesz tworzyć prompty zawierające zwykły tekst, tekst sformatowany, karty, a nawet pełnowymiarowe Prompty HTML obsługiwane przez aplikację internetową z obsługą interaktywnego obszaru roboczego. Dokumentacja podpowiedzi zawiera zawiera szczegółowe informacje na temat tworzenia promptu podczas obsługi zdarzenia webhooka. Te fragmenty kodu wyświetlają prośbę o kartę:

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'
    })
  }));
});

Plik JSON odpowiedzi

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

Parametry intencji odczytu

Gdy środowisko wykonawcze Asystenta pasuje do intencji, wyodrębnia zdefiniowane . Pierwotna właściwość to dane, które użytkownik podał jako dane wejściowe, właściwością rozpoznaną jest, do której NLU rozpoznała dane wejściowe na podstawie typu specyfikacji.

Node.js

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

Żądanie JSON

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

Odczytywanie ustawień regionalnych użytkownika

Ta wartość odpowiada ustawieniu regionalnemu użytkownika w Asystencie Google.

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

Pamięć do odczytu i zapisu

Dokładne informacje na ten temat znajdziesz w dokumentacji dotyczącej miejsca na dane. korzystać z różnych funkcji pamięci masowej.

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

Żądanie JSON

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

Plik JSON odpowiedzi

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

Sprawdź możliwości urządzenia

Możesz sprawdzić możliwości urządzenia, aby zapewnić różne funkcje lub przebieg rozmów.

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");

Żądanie JSON

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

Pełną listę funkcji platformy znajdziesz tutaj: Capability odwołania.

Zastąpienia typu środowiska wykonawczego

Typy środowisk wykonawczych umożliwiają modyfikowanie specyfikacji typów w czasie działania. Możesz użyć tej do wczytywania danych z innych źródeł w celu wypełniania prawidłowych wartości danego typu. Dla: możesz na przykład dodać opcje dynamiczne do ankiety, używając zastąpień typu środowiska wykonawczego pytanie lub dodanie codziennej pozycji do menu.

Aby używać typów środowisk wykonawczych, musisz aktywować webhooka z akcji, który wywołuje w swojej realizacji. Następnie możesz uzupełnić session.typeOverrides w odpowiedzi na działanie. Dostępny(-a) tryby zawierają TYPE_MERGE, aby zachować istniejące wpisy typów, lub TYPE_REPLACE , aby zastąpić istniejące wpisy zastąpieniami.

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']
        },
    ]
  }
}];

Plik JSON odpowiedzi

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

Włącz funkcję promowania mowy

Promowanie mowy umożliwia określenie wskazówek do NLU w celu poprawy dopasowania intencji. Ty może zawierać maksymalnie 1000 wpisów.

Node.js

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

Plik JSON odpowiedzi

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

Sceny przejścia

Oprócz zdefiniowania przejść statycznych w projekcie Actions możesz też powoduje przechodzenie między scenami w czasie działania aplikacji.

Node.js

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

Plik JSON odpowiedzi

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

Odczytaj przedziały sceny

Podczas wypełniania przedziałów możesz użyć realizacji, aby zweryfikować przedział lub sprawdzić stan wypełniania przedziałów (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

Załóżmy na przykład, że chcesz wyodrębnić strefę czasową z odpowiedzi. W W tym przykładzie nazwa boksu to datetime1. Aby uzyskać strefę czasową, użyj:

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

Żądanie JSON

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

Unieważnij przedziały sceny

Możesz unieważnić przedziały i poprosić użytkownika o wpisanie nowej wartości.

Node.js

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

Plik JSON odpowiedzi

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

Opcje programistyczne

Actions Builder udostępnia wbudowany edytor o nazwie edytora Cloud Functions, który pozwala utworzyć i wdrożyć funkcję w Cloud Functions dla Firebase bezpośrednio konsoli. Możesz też utworzyć i wdrożyć realizację w wybranym hostingu i zarejestruj punkt końcowy realizacji HTTPS jako moduł obsługi webhooka.

Edytor wbudowany

Aby programować za pomocą edytora Cloud Functions:

  1. Otwórz projekt w Actions i wejdź na kartę Programowanie > Webhook > Zmień fulfillment_method. Pojawi się okno Metody realizacji.
  2. Wybierz Wbudowane funkcje w Cloud Functions i kliknij Potwierdź.
.

Zewnętrzny punkt końcowy HTTPS

W tej sekcji dowiesz się, jak skonfigurować Cloud Functions dla Firebase jako: usługi realizacji akcji konwersacyjnej. Możesz jednak wdrożyć w wybranej usłudze hostingowej.

Skonfiguruj środowisko

Aby skonfigurować środowisko, wykonaj te czynności:

  1. Pobierz i zainstaluj Node.js.

  2. Skonfiguruj i zainicjuj interfejs wiersza poleceń Firebase. Jeśli następujące polecenie zakończy się niepowodzeniem, błąd EACCES, konieczna może być zmiana uprawnień npm.

    npm install -g firebase-tools

  3. Uwierzytelnij narzędzie Firebase za pomocą konta Google:

    firebase login

  4. Otwórz katalog projektu, w którym został zapisany projekt w Actions. Pojawi się prośba o wybranie funkcji interfejsu wiersza poleceń Firebase, które chcesz skonfigurować w projekcie Actions. Wybierz Functions oraz inne funkcje, które mogą Ci się przydać np. Firestore, a następnie naciśnij Enter, aby potwierdzić i kontynuować:

    $ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init

  5. Powiąż narzędzie Firebase z projektem w Actions, wybierając je za pomocą użyj klawiszy strzałek do poruszania się po liście projektów:

  6. Po wybraniu projektu narzędzie Firebase uruchamia Funkcje, konfiguracji i pyta, jakiego języka chcesz użyć. Wybierz za pomocą klawiszy strzałek i naciśnij Enter, aby kontynuować.

    === 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. Określ, czy chcesz używać ESLint do wychwytywania prawdopodobnych błędów i egzekwowania stylu, wpisując Y lub N:

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

  8. Pobierz zależności projektu, wpisując w prompcie Y:

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

    Po zakończeniu konfiguracji zobaczysz dane wyjściowe podobne do tych:

    ✔  Firebase initialization complete!

  9. Zainstaluj zależność @assistant/conversation:

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

  10. Pobierz zależności realizacji i wdróż funkcję realizacji:

    $ npm install
$ firebase deploy --only functions

    Wdrożenie zajmuje kilka minut. Po zakończeniu zobaczysz w następujący sposób. Będziesz potrzebować adresu URL funkcji, aby wpisać w Dialogflow.

    ✔  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. Skopiuj adres URL realizacji, aby użyć go w następnej sekcji.

Zarejestruj moduł obsługi webhooka

Aby zarejestrować punkt końcowy funkcji w Cloud Functions jako moduł obsługi webhooka:

  1. W Konsoli Actions kliknij Programowanie > Webhook.
  2. Kliknij Zmień metodę realizacji. Okno Metody realizacji
  3. Wybierz Webhook i kliknij Potwierdź.
  4. W polu Webhook wklej adres URL usługi sieciowej.
  5. Kliknij Zapisz.