L'API Transactions verrà ritirata il 3 maggio 2023, prima della disattivazione delle azioni di conversazione il 13 giugno 2023. Per ulteriori informazioni, vedi Ritiro di Azioni di conversazione.

Questa pagina è stata tradotta dall'API Cloud Translation.

Prenotazioni di build

Questa guida ti accompagnerà nel processo di sviluppo di un progetto Actions che utilizza l'API Orders per effettuare prenotazioni.

Flusso delle transazioni

Quando il progetto Actions gestisce le prenotazioni, usa la seguente procedura:

(Facoltativo) Convalida i requisiti della transazione: utilizza le transazioni l'aiuto dei requisiti all'inizio della conversazione per assicurarti l'utente sia in grado di eseguire una transazione.
Crea l'ordine: guida l'utente attraverso una "assemblaggio carrello" dove crea i dettagli della prenotazione.
Proponi l'ordine: una volta che il "carrello" è completa, proponi l'"ordine" di prenotazione a l'utente, in modo che possa verificare che sia corretto. Se la prenotazione viene confermata, ricevi una risposta con i dettagli della prenotazione.
Finalizzare l'ordine e inviare una ricevuta: dopo aver confermato l'ordine, aggiorna il tuo sistema di prenotazione e inviare una ricevuta all'utente.
Inviare aggiornamenti sull'ordine: nel corso del ciclo di vita della prenotazione, fornisci all'utente aggiornamenti sullo stato di prenotazione inviando richieste PATCH al API Orders.

Limitazioni e linee guida per la revisione

Tieni presente che alle Azioni che utilizzano l'opzione transazioni e Orders. La revisione delle azioni può richiedere fino a sei settimane. con le transazioni, quindi tienine conto quando pianifichi il programma delle release. Per semplificare la procedura di revisione, assicurati di rispettare le norme e linee guida per le transazioni prima di inviare l'Azione per la revisione.

Puoi eseguire il deployment di Azioni che utilizzano l'API Orders solo nei seguenti paesi:

Australia
Brasile
Canada
Indonesia

Giappone
Messico
Qatar
Russia

Singapore
Svizzera
Thailandia
Turchia
Regno Unito
Stati Uniti

Crea il tuo progetto

Per un esempio esaustivo di conversazioni transazionali, consulta la nostra sezione Transazioni di esempio in Node.js.

Configurazione

Quando crei l'azione, devi specificare che desideri eseguire delle transazioni nella console Actions.

Per configurare il progetto e il completamento, segui questi passaggi:

Crea un nuovo progetto o importane uno esistente.
Vai a Esegui il deployment > Informazioni sulla directory.
In Altre informazioni > Transazioni > seleziona la casella "Esegui le tue azioni" utilizzare l'API Transactions per eseguire transazioni di beni fisici?".

(Facoltativo) Convalida i requisiti della transazione

Non appena l'utente ha indicato di voler effettuare una prenotazione, devi controllare di poter richiedere una prenotazione. Ad esempio, se richiamata, l'Azione potrebbe chiedi "Vuoi prenotare un posto?". Se l'utente dice "sì", dovresti assicurarsi di poter procedere e dare loro l'opportunità di correggere le impostazioni impedendogli di continuare la transazione. Per farlo, devi transizione a una scena che esegue un controllo dei requisiti di transazione.

Crea requisiti della transazione - Controlla scena

Dalla scheda Scene, aggiungi una nuova scena con il nome TransactionRequirementsCheck.
In Riempimento slot, fai clic su + per aggiungere un nuovo spazio.
In Seleziona tipo, seleziona actions.type.TransactionRequirementsCheckResult come tipo di slot.
Nel campo del nome dell'area, assegna all'area il nome TransactionRequirementsCheck.
Attiva la casella di controllo Personalizza il writeback del valore dell'area (attiva per impostazione predefinita).
Fai clic su Salva.

Un controllo dei requisiti di transazione genera uno dei seguenti risultati:

Se i requisiti sono soddisfatti, il parametro di sessione viene impostato con esito positivo e potrai procedere con la creazione dell'ordine dell'utente.
Se non è possibile soddisfare uno o più requisiti, il parametro sessione viene impostato con una condizione di errore. In questo caso, devi modificare la conversazione dall'esperienza transazionale o terminare la conversazione.
- Se gli errori che restituiscono questo stato possono essere corretti dall'utente, gli verrà chiesto di risolvere i problemi sul proprio dispositivo. Se conversazione in corso su una piattaforma di sola voce, il trasferimento sul telefono dell'utente.

Gestire il risultato del controllo dei requisiti delle transazioni

Dalla scheda Scene, seleziona l'elemento appena creato TransactionRequirementsCheck scena.
In Condizione, fai clic su + per aggiungere una nuova condizione.
Nel campo di testo, inserisci la seguente sintassi della condizione per verificare condizione di operazione riuscita:
```
scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
```
Passa il mouse sopra la condizione appena aggiunta e fai clic sulla Freccia su per posizionarlo prima di if scene.slots.status == "FINAL".
Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente sono pronti a effettuare una transazione:
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            Looks like you're good to go!.
```
In Transizione, seleziona un'altra scena per consentire all'utente di continuare. la conversazione e procedere con la transazione.
Seleziona la condizione else if scene.slots.status == "FINAL".
Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente non sono in grado di effettuare una transazione:
```
candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.
```
In Transizione, seleziona Termina conversazione per terminarla. se un utente non è in grado di effettuare transazioni.

Crea l'ordine

Una volta ottenute le informazioni sull'utente necessarie, crea un "carrello assemblaggio" che guida l'utente nella creazione della prenotazione. Ogni evento L'azione avrà un flusso di assemblaggio del carrello leggermente diverso a seconda del suo completamente gestito di Google Cloud.

In un'esperienza di base di assemblaggio del carrello, un utente seleziona da un elenco delle opzioni da aggiungere alla loro prenotazione, anche se puoi progettare la conversazione per semplificare un'esperienza utente positiva. Ad esempio, crea un'esperienza di assemblaggio del carrello che permetta all'utente di pianificare una prenotazione mensile con una semplice domanda sì o no. Puoi anche presentare all'utente un carosello o una scheda con l'elenco "Consigliati" prenotazioni.

È consigliabile utilizzare risposte dettagliate alle presentare visivamente le opzioni dell'utente, ma anche progettare la conversazione in modo che l'utente può creare il carrello usando solo la voce. Per alcune best practice e esempi di esperienze di assemblaggio del carrello, consulta le linee guida per la progettazione.

Creazione di un ordine

Durante la conversazione, raccogli i dettagli della prenotazione dell'utente e poi creare un oggetto Order.

Il Order deve contenere almeno quanto segue:

buyerInfo: informazioni sull'utente che effettua l'acquisto.
transactionMerchant: informazioni sul commerciante che ha facilitato l'esecuzione dell'ordine.
contents: i contenuti effettivi dell'ordine indicato come lineItems.

di Gemini Advanced.

Consulta il Order la documentazione di risposta per creare il tuo carrello. Tieni presente che potrebbe essere necessario includere campi diversi a seconda della prenotazione.

Il codice di esempio riportato di seguito mostra un ordine di prenotazione completo, inclusi i campi facoltativi:

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

Crea opzioni per ordine e presentazione

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

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

Salva i dati dell'ordine nel parametro di sessione

Dal fulfillment, salva i dati dell'ordine in un parametro di sessione. L'ordine verrà usato in più scene della stessa sessione.

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

Proponi l'ordine

Dopo aver creato un ordine di prenotazione, devi presentarlo all'utente per: confermare o rifiutare. Per farlo, devi passare a una scena che esegue una transazione una decisione presa.

Crea scena decisionale transazione

Dalla scheda Scene, aggiungi una nuova scena con il nome TransactionDecision.
In Riempimento slot, fai clic su + per aggiungere un nuovo spazio.
In Seleziona tipo, seleziona actions.type.TransactionDecisionValue come il tipo di slot.
Nel campo del nome dell'area, assegna all'area il nome TransactionDecision.
Attiva la casella di controllo Personalizza il writeback del valore dell'area (attiva per impostazione predefinita).
In Configura slot, seleziona Utilizza parametro di sessione dal menu a discesa.
In Configura slot,inserisci il nome del parametro di sessione utilizzato archiviare l'ordine nel campo di testo (ad es. $session.params.order).
Fai clic su Salva.

Nel tentativo di riempire uno slot TransactionDecisionValue, l'assistente avvia un'esperienza integrata in cui l'elemento Order che hai trasmesso viene visualizzato direttamente una "scheda di anteprima del carrello". L'utente può dire "prenota prenotazione", rifiuta la transazione o richiedere di modificare i dettagli della prenotazione.

A questo punto l'utente può anche richiedere modifiche all'ordine. In questo caso, assicurati che l'evasione degli ordini possa gestire le richieste di modifica dell'ordine dopo per completare l'esperienza di assemblaggio del carrello.

Gestire il risultato della decisione sulle transazioni

Quando uno slot TransactionDecisionValue viene riempito, la risposta dell'utente alla verrà archiviata in un parametro di sessione. Questo valore contiene le seguenti:

ORDER_ACCEPTED,
ORDER_REJECTED,
CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT.

Per gestire il risultato di una decisione relativa a una transazione:

Dalla scheda Scene, seleziona la scena TransactionDecision appena creata.
In Condizione, fai clic su + per aggiungere una nuova condizione.
Nel campo di testo, inserisci la seguente sintassi della condizione per verificare condizione di operazione riuscita:
```
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
```
Passa il mouse sopra la condizione appena aggiunta e fai clic sulla Freccia su per posizionarlo prima di if scene.slots.status == "FINAL".

Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente la prenotazione è stata completata:

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

In Transizione seleziona Termina conversazione per terminarla.
In Condizione, fai clic su + per aggiungere una nuova condizione.

Nel campo di testo, inserisci la seguente sintassi della condizione per verificare condizioni di errore:

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

Passa il mouse sopra la condizione appena aggiunta e fai clic sulla Freccia su per posizionarlo prima di if scene.slots.status == "FINAL".

Attiva Invia prompt e fornisci un prompt semplice per comunicare all'utente l'ordine è stato rifiutato:

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

In Transizione seleziona Termina conversazione per terminarla.
Seleziona la condizione else if scene.slots.status == "FINAL".

Attiva l'opzione Invia prompt e fornisci un messaggio semplice per informare l'utente non sono in grado di effettuare una transazione:

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

In Transizione, seleziona Termina conversazione per terminarla. se un utente non è in grado di effettuare transazioni.

Finalizza la prenotazione e invia una ricevuta

Quando l'area TransactionDecisionValue restituisce il risultato ORDER_ACCEPTED, devi eseguire immediatamente l'elaborazione richiesta per pianificare (ad esempio, rimanendo in modo permanente nel tuo database).

Invia una risposta semplice per alimentare la conversazione. L'utente riceve un "scheda ricevuta compressa" insieme alla tua risposta.

Per inviare un aggiornamento iniziale dell'ordine:

Dalla scheda Scene, seleziona la tua TransactionDecision scena.

In Condizione, seleziona la condizione che verifica il risultato con esito positivo. ORDER_ACCEPTED:

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

Per questa condizione, attiva Chiama il webhook e fornisci un intent nome del gestore, ad esempio update_order.

Nel codice webhook, aggiungi un gestore di intent per l'invio di un aggiornamento iniziale dell'ordine:

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

Invia aggiornamenti sull'ordine

Lo stato della prenotazione cambia nel corso della sua durata. Invia l'utente degli aggiornamenti degli ordini di prenotazione con richieste PATCH HTTP all'API Orders, lo stato e i dettagli dell'ordine.

Configura richieste asincrone all'API Orders

Le richieste di aggiornamento degli ordini all'API Orders sono autorizzate da un accesso di accesso. Per eseguire il PATCH di un aggiornamento dell'ordine all'API Orders, scarica un file JSON chiave dell'account di servizio associata al progetto Actions Console, quindi la chiave dell'account di servizio per un token di connessione che può essere passato Intestazione Authorization della richiesta HTTP.

Per recuperare la chiave dell'account di servizio, segui questi passaggi:

Nella console Google Cloud, Vai a Menu SFTP > API e Servizi > Credenziali > Crea le credenziali > Chiave account di servizio.
In Account di servizio, seleziona Nuovo account di servizio.
Imposta l'account di servizio su service-account.
Imposta Ruolo su Progetto > Proprietario.
Imposta il tipo di chiave su JSON.
Seleziona Crea.
Una chiave dell'account di servizio JSON privata verrà scaricata sulla macchina locale.

Nel codice di aggiornamento dell'ordine, sostituisci la chiave di servizio con un token di connessione utilizzando la libreria client delle API di Google Ambito "https://www.googleapis.com/auth/actions.order.developer". Puoi visualizzare passaggi di installazione ed esempi sulla libreria client API Pagina GitHub.

Riferimento order-update.js nel nostro esempio di Node.js per un esempio di scambio di chiavi.

Invia aggiornamenti sull'ordine

Dopo aver scambiato la chiave dell'account di servizio con un token di connessione OAuth, invia aggiornamenti degli ordini come richieste PATCH autorizzate all'API Orders.

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

Fornisci le seguenti intestazioni nella tua richiesta:

"Authorization: Bearer token" con il token di connessione OAuth con cui hai scambiato la chiave dell'account di servizio.
"Content-Type: application/json".

La richiesta PATCH deve avere un corpo JSON nel seguente formato:

{ "orderUpdate": OrderUpdate }

La OrderUpdate è costituito dai seguenti campi di primo livello:

updateMask. I campi dell'ordine che stai aggiornando. Per aggiornare stato della prenotazione, imposta il valore su reservation.status, reservation.userVisibleStatusLabel.
order: i contenuti dell'aggiornamento. Se stai aggiornando il contenuti della prenotazione, imposta il valore sull'oggetto Order aggiornato. Se stai solo aggiornando lo stato della prenotazione (ad esempio, da da "PENDING" a "FULFILLED"), l'oggetto contiene seguenti campi:
- merchantOrderId: lo stesso ID impostato nell'oggetto Order.
- lastUpdateTime: il timestamp di questo aggiornamento.
- purchase: un oggetto che contiene:
  - status: lo stato dell'ordine come ReservationStatus, ad esempio "CONFIRMED" o "CANCELLED".
  - userVisibleStatusLabel: un'etichetta rivolta agli utenti che fornisce dettagli su lo stato dell'ordine, ad esempio "La prenotazione è confermata".
userNotification (facoltativo) - A userNotification che può essere visualizzato sul dispositivo dell'utente quando viene inviato questo aggiornamento. Nota che l'inclusione di questo oggetto non garantisce la visualizzazione di dal dispositivo dell'utente.

Il seguente codice campione mostra un esempio OrderUpdate che aggiorna la stato dell'ordine di prenotazione a 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}`);
}

Impostare lo stato della prenotazione

Aggiornamento di un ordine: ReservationStatus deve descrivere lo stato attuale dell'ordine. Nel tuo aggiornamento (order.ReservationStatus) utilizza uno dei seguenti valori:

PENDING - La prenotazione è stata "creata" dall'Azione ma richiede un'ulteriore elaborazione sul tuo backend.
CONFIRMED - La prenotazione è confermata nel back-end della tua programmazione.
CANCELLED - L'utente ha annullato la prenotazione.
FULFILLED: la prenotazione dell'utente è stata evasa dal servizio.
CHANGE_REQUESTED - L'utente ha richiesto una modifica alla prenotazione e la modifica è in fase di elaborazione.
REJECTED - Se non sei stato in grado di elaborare o altrimenti conferma la prenotazione.

Invia aggiornamenti sull'ordine per ogni stato pertinente per il tuo prenotazione. Ad esempio, se la tua prenotazione richiede l'elaborazione manuale per conferma la prenotazione dopo averla richiesta, invia un aggiornamento dell'ordine di PENDING fino al giorno l'ulteriore elaborazione viene eseguita. Non tutte le prenotazioni richiedono ogni valore di stato.

Testa il progetto

Durante il test del progetto, puoi abilitare la modalità sandbox nella console di Actions per testare l'Azione senza addebitare l'importo su un metodo di pagamento. Per attivare la modalità sandbox:

Nella console di Actions, fai clic su Test nel menu di navigazione.
Fai clic su Impostazioni.
Attiva l'opzione Sandbox per lo sviluppo.

Per le transazioni fisiche, puoi anche impostare il campo isInSandbox su true in del campione. Questa azione equivale ad attivare l'impostazione della modalità sandbox in la console Actions. Per visualizzare uno snippet di codice che utilizza isInSandbox, consulta le Sezione Inviare aggiornamenti sull'ordine.

Risoluzione dei problemi

Se riscontri problemi durante i test, leggi la nostra procedura per la risoluzione dei problemi. per le transazioni.