Tworzenie rezerwacji

Ten przewodnik przedstawia proces tworzenia projektu w Actions. który do składania rezerwacji używa interfejsu Orders API.

Przepływ transakcji

Gdy projekt w Actions obsługuje rezerwacje, korzysta z takiego procesu:

  1. Wymagania dotyczące weryfikacji transakcji (opcjonalnie) – użyj transakcji wymagań aplikacji na początku rozmowy. może zrealizować transakcję.
  2. Ustal kolejność – pokaż użytkownikowi „skład koszyka” gdzie podają szczegóły rezerwacji.
  3. Zaproponuj zamówienie – gdy „koszyk” zakończono, zaproponuj „zamówienie” rezerwacji do użytkownika, aby mógł potwierdzić, że jest poprawny. Jeśli rezerwacja zostanie potwierdzona, otrzyma odpowiedź ze szczegółami rezerwacji.
  4. Sfinalizuj zamówienie i wyślij potwierdzenie – po potwierdzeniu zamówienia zaktualizuj system rezerwacji i wysłać użytkownikowi potwierdzenie.
  5. Wysyłaj aktualne informacje o zamówieniu – w trakcie okresu ważności rezerwacji aktualizować stan rezerwacji użytkownika, wysyłając żądania PATCH do Orders API.

Ograniczenia i wytyczne dotyczące sprawdzania

Pamiętaj, że w przypadku akcji, które korzystają z tagu do transakcji i do interfejsu Orders API. Weryfikacja działań może zająć do 6 tygodni Transakcje, więc weź ten czas pod uwagę przy planowaniu harmonogramu publikacji. Aby uprościć proces weryfikacji, przestrzegaj zasadami i wytycznymi dotyczącymi transakcji przed przesłaniem Akcji do sprawdzenia.

Działania używające interfejsu Orders API możesz wdrażać tylko w tych krajach:

Australia
Brazylia
Kanada
Indonezja, 		Japonia
Meksyk
Katar
Rosja 		Singapur
Szwajcaria
Tajlandia
Turcja
Wielka Brytania
Stany Zjednoczone

Kompilowanie projektu

Szczegółowy przykład rozmów transakcyjnych można znaleźć w sekcji Transakcje w środowisku Node.js.

Konfiguracja

Tworząc akcję, musisz określić, że chcesz dokonywać transakcji. w Konsoli działań.

Aby skonfigurować projekt i realizację:

  1. Utwórz nowy projekt lub zaimportuj istniejący.
  2. Przejdź do Wdróż > Informacje o katalogu.

  3. W sekcji Dodatkowe informacje > Transakcje > zaznacz pole z napisem „Wykonuj działania”. używać interfejsu Transaction API do przeprowadzania transakcji na towary fizyczne?”.

Wymagania dotyczące weryfikacji transakcji (opcjonalne)

Gdy tylko użytkownik wskaże, że chce utworzyć rezerwację, że mogą poprosić o rezerwację. Na przykład po wywołaniu akcja może zapytaj: „Czy chcesz zarezerwować miejsce?”. Jeśli użytkownik odpowie „tak”, aby klient mógł przejść dalej i dać mu możliwość poprawienia ustawień co uniemożliwia kontynuowanie transakcji. W tym celu przejście do sceny, która sprawdza wymagania dotyczące transakcji.

Utwórz scenę kontroli wymagań dotyczących transakcji

  1. Na karcie Sceny dodaj nową scenę o nazwie. TransactionRequirementsCheck
  2. W sekcji Wypełnianie boksu kliknij +, aby dodać nowy boks.
  3. W sekcji Wybierz typ kliknij actions.type.TransactionRequirementsCheckResult. .
  4. W polu nazwy boksu wpisz nazwę TransactionRequirementsCheck.
  5. Zaznacz pole wyboru Dostosuj zapis wartości przedziału (domyślnie włączone).

  6. Kliknij Zapisz.

Po sprawdzeniu wymagań transakcji następuje jeden z tych wyników:

  • Jeśli wymagania są spełnione, parametr sesji zostaje ustawiony z powodem i możesz kontynuować tworzenie zamówienia użytkownika.
  • Jeśli nie można spełnić co najmniej jednego z wymagań, parametr sesji ma postać z warunkiem błędu. W takim przypadku należy zmienić temat oderwanie się od transakcji lub zakończenie rozmowy.
    • Jeśli użytkownik może naprawić błędy, które spowodowały niepowodzenie, zobaczy prośbę o rozwiązanie tych problemów na urządzeniu. Jeśli rozmowy są prowadzone na platformie, która jest przeznaczona tylko do komunikacji głosowej, należy zainicjować na telefonie użytkownika.

Wynik kontroli wymagań dotyczących transakcji

  1. Na karcie Sceny wybierz nowo utworzony element. TransactionRequirementsCheck scena.
  2. W sekcji Warunek kliknij +, by dodać nowy warunek.

  3. W polu tekstowym wpisz poniższą składnię warunku, aby sprawdzić warunek sukcesu:

    scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"

  4. Najedź kursorem na dodany warunek i kliknij strzałkę w górę aby umieścić ją przed if scene.slots.status == "FINAL".

  5. Włącz Wysyłaj potwierdzenia i wyświetlaj proste prompty, które dadzą użytkownikowi znać. jest gotowy do dokonania transakcji:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Looks like you're good to go!.

  6. W sekcji Przejście wybierz inną scenę, pozwalając użytkownikowi przejść dalej. rozmowę i dokonywać transakcji.

  7. Wybierz warunek else if scene.slots.status == "FINAL".

  8. Włącz Wysyłaj potwierdzenia i wyświetlaj proste prompty, które dadzą użytkownikowi znać. nie mogą dokonać transakcji:

    candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.

  9. W sekcji Przenoszenie wybierz Zakończ rozmowę, aby zakończyć rozmowę. jeśli użytkownik nie może dokonać transakcji.

Tworzenie zamówienia

Po zgromadzeniu potrzebnych informacji o użytkowniku utwórz „koszyk”, montaż” która pomaga użytkownikowi zrobić rezerwację. Co Procedura składania koszyka będzie wyglądał trochę inaczej, zależnie od potrzeb posprzedażna.

W podstawowym procesie składania koszyka użytkownik wybiera z listy opcje, które chce dodać do rezerwacji, chociaż możesz tak zaplanować rozmowę, aby uprościć użytkowników. Stwórz na przykład środowisko składania koszyków, które umożliwia zarezerwowanie miesięcznej rezerwacji, odpowiadając na pytanie typu „tak” lub „nie”. Możesz też pokazać użytkownikowi kartę karuzeli lub z listą „Polecane” rezerwacji.

Zalecamy używanie odpowiedzi rozszerzonych do nie tylko prezentować użytkownikowi opcje wizualne, ale też tak zaprojektować rozmowę, użytkownicy mogą tworzyć koszyk, używając jedynie głosu. Kilka sprawdzonych metod przykładów rozwiązań do składania koszyków – przeczytaj wskazówki dotyczące projektowania.

Tworzenie zamówienia

Podczas rozmowy zbierz szczegóły rezerwacji użytkownika, utworzyć obiekt Order.

Order musi zawierać przynajmniej te elementy:

  • buyerInfo – informacje o użytkowniku dokonującym zakupu.
  • transactionMerchant – informacje o sprzedawcy, który zrealizował zamówienie.
  • contents – rzeczywista treść zamówienia podana jako lineItems.
.

Więcej informacji: Order z dokumentacją odpowiedzialną do tworzenia koszyka. Pamiętaj, że może być konieczne dodanie atrybutu różne pola w zależności od rezerwacji.

Przykładowy kod poniżej przedstawia kompletne zamówienie rezerwacji, w tym pola opcjonalne:

const order = {
   createTime: '2019-09-24T18:00:00.877Z',
   lastUpdateTime: '2019-09-24T18:00:00.877Z',
   merchantOrderId: orderId, // A unique ID String for the order
   userVisibleOrderId: orderId,
   transactionMerchant: {
     id: 'http://www.example.com',
     name: 'Example Merchant',
   },
   contents: {
     lineItems: [
       {
         id: 'LINE_ITEM_ID',
         name: 'Dinner reservation',
         description: 'A world of flavors all in one destination.',
         reservation: {
           status: 'PENDING',
           userVisibleStatusLabel: 'Reservation is pending.',
           type: 'RESTAURANT',
           reservationTime: {
             timeIso8601: '2020-01-16T01:30:15.01Z',
           },
           userAcceptableTimeRange: {
             timeIso8601: '2020-01-15/2020-01-17',
           },
           partySize: 6,
           staffFacilitators: [
             {
               name: 'John Smith',
             },
           ],
           location: {
             zipCode: '94086',
             city: 'Sunnyvale',
             postalAddress: {
               regionCode: 'US',
               postalCode: '94086',
               administrativeArea: 'CA',
               locality: 'Sunnyvale',
               addressLines: [
                 '222, Some other Street',
               ],
             },
           },
         },
       },
     ],
   },
   buyerInfo: {
     email: 'janedoe@gmail.com',
     firstName: 'Jane',
     lastName: 'Doe',
     displayName: 'Jane Doe',
   },
   followUpActions: [
     {
       type: 'VIEW_DETAILS',
       title: 'View details',
       openUrlAction: {
         url: 'http://example.com',
       },
     },
     {
       type: 'CALL',
       title: 'Call us',
       openUrlAction: {
         url: 'tel:+16501112222',
       },
     },
     {
       type: 'EMAIL',
       title: 'Email us',
       openUrlAction: {
         url: 'mailto:person@example.com',
       },
     },
   ],
   termsOfServiceUrl: 'http://www.example.com'
 };

Utwórz opcje kolejności i prezentacji

const orderOptions = {
      'requestDeliveryAddress': false,
    };

const presentationOptions = {
      'actionDisplayName': 'RESERVE'
    };

Zapisz dane zamówienia w parametrze sesji

Zapisz dane zamówienia ze strony realizacji zamówienia w parametrze sesji. zamówienie; będzie używany w różnych scenach w tej samej sesji.

conv.session.params.order = {
    '@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
    order: order,
    orderOptions: orderOptions,
    presentationOptions: presentationOptions
};

Zaproponuj zamówienie

Po utworzeniu zamówienia rezerwacji należy przedstawić je użytkownikowi potwierdzić lub odrzucić. Aby to zrobić, przejdź do sceny, w której realizuje transakcję decyzji.

Utwórz scenę decyzji dotyczącej transakcji

  1. Na karcie Sceny dodaj nową scenę o nazwie TransactionDecision.
  2. W sekcji Wypełnianie boksu kliknij +, aby dodać nowy boks.
  3. W sekcji Wybierz typ wybierz opcję actions.type.TransactionDecisionValue jako typu boksu.
  4. W polu nazwy boksu wpisz nazwę TransactionDecision.
  5. Zaznacz pole wyboru Dostosuj zapis wartości przedziału (domyślnie włączone).
  6. W sekcji Skonfiguruj przedział wybierz w menu Użyj parametru sesji.
  7. W sekcji Skonfiguruj przedział wpisz nazwę parametru sesji używanego do zapisz zamówienie w polu tekstowym (np. $session.params.order).

  8. Kliknij Zapisz.

Aby wypełnić miejsce w aplikacji TransactionDecisionValue, Asystent inicjuje dzięki wbudowanemu interfejsowi, w którym przekazana wartość Order jest renderowana bezpośrednio „karty podglądu koszyka”. Użytkownik może powiedzieć „zaplanuj rezerwację”, odrzucić transakcję lub poprosić o zmianę szczegółów rezerwacji.

Na tym etapie użytkownik może również poprosić o zmianę zamówienia. W tym przypadku powinna umożliwiać realizację żądań zmiany zamówienia po i kończę składanie koszyka.

Obsługa wyniku decyzji dotyczącej transakcji

Gdy boks TransactionDecisionValue zostanie wypełniony, odpowiedź użytkownika na jest przechowywana w parametrze sesji. Ta wartość zawiera następujące:

  • ORDER_ACCEPTED,
  • ORDER_REJECTED,
  • CART_CHANGE_REQUESTED
  • USER_CANNOT_TRANSACT.

Aby obsługiwać wynik decyzji dotyczącej transakcji:

  1. Na karcie Sceny wybierz nowo utworzoną scenę TransactionDecision.
  2. W sekcji Warunek kliknij +, by dodać nowy warunek.

  3. W polu tekstowym wpisz poniższą składnię warunku, aby sprawdzić warunek sukcesu:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

  4. Najedź kursorem na dodany warunek i kliknij strzałkę w górę aby umieścić ją przed if scene.slots.status == "FINAL".

  5. Włącz Wysyłaj potwierdzenia i wyświetlaj proste prompty, które dadzą użytkownikowi znać. realizacja rezerwacji:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction completed! Your reservation
            $session.params.TransactionDecision.order.merchantOrderId is all
            set!

  6. W sekcji Przenoszenie wybierz Zakończ rozmowę, aby zakończyć rozmowę.

  7. W sekcji Warunek kliknij +, by dodać nowy warunek.

  8. W polu tekstowym wpisz poniższą składnię warunku, aby sprawdzić warunki błędu:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"

  9. Najedź kursorem na dodany warunek i kliknij strzałkę w górę aby umieścić ją przed if scene.slots.status == "FINAL".

  10. Włącz Wysyłaj prompty i wyświetlaj proste prompty, w których poinformujesz użytkownika zamówienie zostało odrzucone:

    candidates:
  - first_simple:
      variants:
        - speech: Looks like you don't want to set up a reservation. Goodbye.

  11. W sekcji Przenoszenie wybierz Zakończ rozmowę, aby zakończyć rozmowę.

  12. Wybierz warunek else if scene.slots.status == "FINAL".

  13. Włącz Wysyłaj potwierdzenia i wyświetlaj proste prompty, które dadzą użytkownikowi znać. nie mogą dokonać transakcji:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction failed with status
            $session.params.TransactionDecision.transactionDecision

  14. W sekcji Przenoszenie wybierz Zakończ rozmowę, aby zakończyć rozmowę. jeśli użytkownik nie może dokonać transakcji.

Dokończ rezerwację i wyślij rachunek

Gdy boks TransactionDecisionValue zwróci wynik ORDER_ACCEPTED, musisz natychmiast wykonać wszelkie czynności konieczne do zaplanowania z rezerwacji (np. utrwalenia we własnej bazie danych).

Wyślij prostą odpowiedź, aby podtrzymywać rozmowę. Użytkownik otrzymuje „zwinięta karta z potwierdzeniem zakupu” wraz z Twoją odpowiedzią.

Aby wysłać początkową aktualizację zamówienia:

  1. Na karcie Sceny wybierz scenę TransactionDecision.

  2. W sekcji Warunek wybierz warunek, który sprawdza uzyskanie wyniku ORDER_ACCEPTED:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

  3. W przypadku tego warunku włącz opcję Wywołaj webhooka i podaj intencję nazwa modułu obsługi, np. update_order.

  4. W kodzie webhooka dodaj moduł obsługi intencji do wysyłania początkowej aktualizacji zamówienia:

    app.handle('update_order', conv => {
  const currentTime = new Date().toISOString();
  let order = conv.session.params.TransactionDecision.order;
  conv.add(new OrderUpdate({
    'updateMask': {
      'paths': [
        'reservation.status',
        'reservation.user_visible_status_label',
        'reservation.confirmation_code'
      ]
    },
    'order': {
      'merchantOrderId': order.merchantOrderId,
      'lastUpdateTime': currentTime,
      'reservation': {
        'status': 'CONFIRMED',
        'userVisibleStatusLabel': 'Reservation confirmed',
        'confirmationCode': '123ABCDEFGXYZ',
      },
    },
    'reason': 'Reason string'
  }));
});

Wysyłaj aktualne informacje o zamówieniu

Stan rezerwacji zmienia się wraz z upływem czasu trwania. Wysyłanie użytkownika aktualizacje zamówień z rezerwacji za pomocą żądań HTTP PATCH kierowanych do interfejsu Orders API, które zawierają ciąg stan i szczegóły zamówienia.

Konfigurowanie żądań asynchronicznych do interfejsu Orders API

Żądania aktualizacji zamówień do interfejsu Orders API są autoryzowane przez dostęp token. Aby uzupełnić aktualizację zamówienia do interfejsu Orders API, pobierz plik JSON klucz konta usługi powiązany z projektem w Konsoli Actions, a następnie klucz konta usługi dla tokena okaziciela, który można przekazać do Nagłówek Authorization żądania HTTP.

Aby pobrać klucz konta usługi, wykonaj te czynności:

  1. W konsoli Google Cloud: przejdź do Menu &#9776 > Interfejsy API Usługi > Dane logowania > Utwórz dane logowania > Klucz konta usługi.
  2. W sekcji Konto usługi wybierz Nowe konto usługi.
  3. Ustaw konto usługi na service-account.
  4. Ustaw Rola na Projekt > Właściciel.
  5. Ustaw typ klucza na JSON.
  6. Kliknij Utwórz.
  7. Prywatny klucz konta usługi JSON zostanie pobrany na Twój komputer lokalny.

W kodzie aktualizacji zamówienia wymień klucz usługi na token okaziciela za pomocą biblioteki klienta interfejsów API Google, Zakres "https://www.googleapis.com/auth/actions.order.developer". Więcej kroki instalacji i przykłady dotyczące biblioteki klienta API Strona GitHub.

Odwołaj się do order-update.js w przykładzie na Node.js .

Wysyłaj aktualne informacje o zamówieniu

Po wymianie klucza konta usługi na token okaziciela OAuth wyślij aktualizacje zamówień jako autoryzowane żądania PATCH wysyłane do interfejsu Orders API.

Adres URL interfejsu Orders API: PATCH https://actions.googleapis.com/v3/orders/${orderId}

Umieść w żądaniu te nagłówki:

  • "Authorization: Bearer token" z tokenem okaziciela OAuth dla którego wymieniono klucz konta usługi.
  • "Content-Type: application/json".

Żądanie PATCH powinno przyjąć treść JSON w tym formacie:

{ "orderUpdate": OrderUpdate }

OrderUpdate obiekt składa się z następujących pól najwyższego poziomu:

  • updateMask – pola aktualizowanego zamówienia. Aby zaktualizować stan rezerwacji, ustaw wartość na reservation.status, reservation.userVisibleStatusLabel.

  • order – zawartość aktualizacji. Jeśli aktualizujesz treści rezerwacji, ustaw wartość na zaktualizowany obiekt Order. Jeśli tylko aktualizujesz stan rezerwacji (na przykład z od "PENDING" do "FULFILLED"), obiekt zawiera tych pól:

    • merchantOrderId – identyfikator, który został ustawiony w obiekcie Order.
    • lastUpdateTime – sygnatura czasowa aktualizacji.
    • purchase – obiekt zawierający:
      • status – stan zamówienia (ReservationStatus), na przykład „CONFIRMED” lub „CANCELLED”.
      • userVisibleStatusLabel – etykieta dla użytkownika zawierająca szczegółowe informacje stan zamówienia, np. „Rezerwacja została potwierdzona”.

  • userNotification (opcjonalnie) – A userNotification do wyświetlenia na urządzeniu użytkownika po wysłaniu tej aktualizacji. Notatka że uwzględnienie tego obiektu nie gwarantuje, że powiadomienie na urządzeniu użytkownika.

Poniżej znajduje się przykładowy kod OrderUpdate, który aktualizuje stan zamówienia rezerwacji na FULFILLED:

// Import the 'googleapis' module for authorizing the request.
const {google} = require('googleapis');
// Import the 'request-promise' module for sending an HTTP POST request.
const request = require('request-promise');
// Import the OrderUpdate class from the client library.
const {OrderUpdate} = require('@assistant/conversation');

// Import the service account key used to authorize the request.
// Replacing the string path with a path to your service account key.
// i.e. const serviceAccountKey = require('./service-account.json')

// Create a new JWT client for the Actions API using credentials
// from the service account key.
let jwtClient = new google.auth.JWT(
   serviceAccountKey.client_email,
   null,
   serviceAccountKey.private_key,
   ['https://www.googleapis.com/auth/actions.order.developer'],
   null,
);

// Authorize the client
let tokens = await jwtClient.authorize();

// Declare the ID of the order to update.
const orderId = '<UNIQUE_MERCHANT_ORDER_ID>';

// Declare order update
const orderUpdate = new OrderUpdate({
   updateMask: {
     paths: [
       'contents.lineItems.reservation.status',
       'contents.lineItems.reservation.userVisibleStatusLabel'
     ]
   },
   order: {
     merchantOrderId: orderId, // Specify the ID of the order to update
     lastUpdateTime: new Date().toISOString(),
     contents: {
       lineItems: [
         {
           reservation: {
             status: 'FULFILLED',
             userVisibleStatusLabel: 'Reservation fulfilled',
           },
         }
       ]
     },
   },
   reason: 'Reservation status was updated to fulfilled.',
});

// Set up the PATCH request header and body,
// including the authorized token and order update.
let options = {
 method: 'PATCH',
 uri: `https://actions.googleapis.com/v3/orders/${orderId}`,
 auth: {
   bearer: tokens.access_token,
 },
 body: {
   header: {
     isInSandbox: true,
   },
   orderUpdate,
 },
 json: true,
};

// Send the PATCH request to the Orders API.
try {
 await request(options);
} catch (e) {
 console.log(`Error: ${e}`);
}

Ustawianie stanu rezerwacji

Identyfikator ReservationStatus aktualizacji zamówienia musi opisywać bieżący stan zamówienia. W grupie order.ReservationStatus aktualizacji użyj jednej z tych wartości:

  • PENDING – rezerwacja została „utworzona” przez akcję, ale wymaga dodatkowe przetwarzanie w Twoim zapleczu.
  • CONFIRMED – rezerwacja została potwierdzona w backendzie do planowania.
  • CANCELLED – użytkownik anulował rezerwację.
  • FULFILLED – rezerwacja użytkownika została zrealizowana przez usługę.
  • CHANGE_REQUESTED – użytkownik poprosił o zmianę rezerwacji, która została wprowadzona. w trakcie przetwarzania danych.
  • REJECTED – jeśli nie udało się przetworzyć lub masz inne problemy potwierdzić rezerwację.

Wysyłaj aktualne informacje o zamówieniach o każdym stanie powiązanym z rezerwacji. Jeśli na przykład Twoja rezerwacja wymaga ręcznego przetwarzania, aby potwierdź rezerwację po przesłaniu prośby, wyślij aktualizację dotyczącą zamówienia u sprzedawcy PENDING do że jest wykonywane dodatkowe przetwarzanie. Nie każda rezerwacja wymaga każdej wartości stanu.

Testowanie projektu

Podczas testowania projektu możesz włączyć tryb piaskownicy w Konsoli Actions aby przetestować Akcję bez obciążania formy płatności. Aby włączyć tryb piaskownicy, wykonaj te czynności:

  1. W Konsoli Actions kliknij Przetestuj w panelu nawigacyjnym.
  2. Kliknij Ustawienia.
  3. Włącz opcję Piaskownica programowania.

W przypadku transakcji fizycznych możesz też ustawić pole isInSandbox na true próbkę. To działanie jest równoważne włączeniu ustawienia trybu piaskownicy w: w Konsoli Actions. Aby zobaczyć fragment kodu, który korzysta z pola isInSandbox, zobacz Sekcja Wysyłaj aktualne informacje o zamówieniu.

Rozwiązywanie problemów

Jeśli podczas testowania wystąpią jakiekolwiek problemy, przeczytaj artykuł o rozwiązywaniu problemów. transakcji.