L'API Transactions sera abandonnée le 3 mai 2023, avant l'abandon des actions de conversation le 13 juin 2023. Pour en savoir plus, consultez Abandon de la fonctionnalité Conversation.

Cette page a été traduite par l'API Cloud Translation.

Créer des réservations

Ce guide vous accompagne tout au long du processus de développement d'un projet Actions. qui utilise Orders API pour effectuer des réservations.

Flux de transactions

Lorsque votre projet Actions gère les réservations, utilise le flux suivant:

Validez les exigences relatives aux transactions (facultatif) : utilisez les transactions. au début de la conversation pour vous assurer que l'utilisateur est capable d'effectuer une transaction.
Créer l'ordre : guidez l'utilisateur tout au long d'une "montage chariot" où il construit les détails de sa réservation.
Proposez la commande : une fois le panier est terminée, proposez la réservation "order" à l’utilisateur, afin qu’il puisse confirmer qu’elle est correcte. Si la réservation est confirmée, reçoivent une réponse avec les détails de la réservation.
Finalisez la commande et envoyez un reçu : une fois la commande confirmée, mettez à jour votre système de réservation et envoyer un reçu à l'utilisateur.
Envoyer des mises à jour de la commande : au cours de la durée de vie de la réservation, des mises à jour de l'état de la réservation de l'utilisateur en envoyant des requêtes PATCH au Orders API.

Restrictions et consignes relatives aux avis

N'oubliez pas que des règles supplémentaires s'appliquent aux actions qui utilisent les Transactions et Orders API. L'examen des actions peut prendre jusqu'à six semaines avec les transactions, alors tenez compte de ce temps lors de la planification de votre calendrier de publication. Pour faciliter le processus d'examen, veillez à respecter les Règles et consignes concernant les transactions avant de soumettre votre action pour examen.

Vous ne pouvez déployer des actions qui utilisent Orders API que dans les pays suivants:

Australie
Brésil
Canada
Indonésie

Japon
Mexique
Qatar
Russie

Singapour
Suisse
Thaïlande
Turquie
Royaume-Uni
États-Unis

Compiler votre projet

Pour obtenir des exemples complets de conversations transactionnelles, consultez notre page Transactions dans Node.js.

Configuration

Lorsque vous créez votre action, vous devez indiquer que vous souhaitez effectuer des transactions dans la console Actions.

Pour configurer votre projet et votre fulfillment, procédez comme suit:

Créez un projet ou importez un projet existant.
Accédez à Déployer > Informations de l'annuaire.
Sous Informations supplémentaires > Transactions > cochez la case "Do your Actions (Actions utiliser l'API Transactions pour effectuer des transactions de biens physiques.

Valider les exigences concernant les transactions (facultatif)

Dès que l'utilisateur a indiqué qu'il souhaite créer une réservation, vous devez vérifier de pouvoir demander une réservation. Par exemple, lorsqu'elle est appelée, votre action peut demandez : "Souhaitez-vous réserver une place ?" Si l'utilisateur dit « oui », vous devez s'assurer qu'il peut continuer et lui donner la possibilité de corriger les paramètres l’empêchant de poursuivre la transaction. Pour ce faire, vous devez une transition vers une scène qui effectue une vérification des exigences liées aux transactions.

Créer une scène de vérification des exigences liées aux transactions

Dans l'onglet Scenes (Scènes), ajoutez une scène portant le nom TransactionRequirementsCheck
Sous Remplissage de cases, cliquez sur + pour ajouter un emplacement.
Sous Sélectionner un type, choisissez actions.type.TransactionRequirementsCheckResult. comme type d'emplacement.
Dans le champ "Nom de l'emplacement", attribuez le nom TransactionRequirementsCheck à l'emplacement.
Cochez la case Personnaliser l'écriture de la valeur de l'emplacement (activée par défaut).
Cliquez sur Enregistrer.

Une vérification des exigences relatives aux transactions permet d'obtenir l'un des résultats suivants:

Si les conditions sont remplies, le paramètre de session est défini avec succès. et vous pouvez passer à la création de la commande de l'utilisateur.
Si une ou plusieurs des conditions ne peuvent pas être remplies, le paramètre de session est défini avec une condition d'échec. Dans ce cas, vous devez recentrer la conversation de l'expérience transactionnelle ou mettre fin à la conversation.
- Si des erreurs entraînant l'état d'échec peuvent être corrigées par l'utilisateur, il sera invité à résoudre ces problèmes sur son appareil. Si le a lieu sur une surface uniquement vocale, un transfert sur le téléphone de l'utilisateur.

Gérer le résultat de la vérification des exigences liées aux transactions

Dans l'onglet Scenes (Scènes), sélectionnez les scènes que vous venez de créer. Scène TransactionRequirementsCheck.
Sous Condition, cliquez sur + pour ajouter une condition.
Dans le champ de texte, saisissez la syntaxe de condition suivante pour vérifier la valeur condition de réussite:
```
scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
```
Pointez sur la condition que vous venez d'ajouter, puis cliquez sur la flèche vers le haut pour la placer avant if scene.slots.status == "FINAL".
Activez l'option Send invites (Envoyer des invites) et fournissez une invite simple pour avertir l'utilisateur. il est prêt à effectuer une transaction:
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            Looks like you're good to go!.
```
Sous Transition, sélectionnez une autre scène, ce qui permet à l'utilisateur de continuer. la conversation et de procéder à la transaction.
Sélectionnez la condition else if scene.slots.status == "FINAL".
Activez l'option Send invites (Envoyer des invites) et fournissez une invite simple pour avertir l'utilisateur. s'il n'est pas en mesure d'effectuer une transaction:
```
candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.
```
Sous Transition, sélectionnez End conversation (Terminer la conversation) pour mettre fin à la conversation. si un utilisateur n'est pas en mesure d'effectuer des transactions.

Créer la commande

Une fois que vous avez les informations utilisateur dont vous avez besoin, construisez un « panier assemblage" expérience qui guide l'utilisateur dans la création de sa réservation. Toutes les Le processus d'assemblage du chariot varie légèrement en fonction des Google Cloud.

Dans une expérience de base d'assemblage du panier, un utilisateur sélectionne des options dans une liste à ajouter à leur réservation, mais vous pouvez concevoir la conversation de façon à simplifier l'expérience utilisateur. Par exemple, créez une expérience d'assemblage de chariot qui permet au de planifier une réservation mensuelle avec une simple question par oui ou non. Vous pouvez également présenter à l'utilisateur une fiche de carrousel ou de liste "recommandé" des réservations.

Nous vous recommandons d'utiliser des réponses enrichies pour présenter visuellement les options de l'utilisateur, mais également concevoir la conversation de sorte que l'utilisateur peut créer son panier en utilisant uniquement sa voix. Pour connaître quelques bonnes pratiques et des exemples d'assemblage de panier, consultez les consignes de conception.

Créer une commande

Tout au long de votre conversation, recueillez les détails de la réservation de l'utilisateur, puis construire un objet Order.

Votre Order doit au minimum contenir les éléments suivants:

buyerInfo : informations sur l'utilisateur effectuant l'achat.
transactionMerchant : informations sur le marchand qui a facilité la commande.
contents : contenu réel de la commande indiqué comme lineItems.

Consultez la Order documentation de réponse pour créer votre panier. Notez que vous devrez peut-être inclure différents champs selon la réservation.

L'exemple de code ci-dessous montre une commande de réservation complète, avec des champs facultatifs:

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

Options de création d'ordre et de présentation

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

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

Enregistrer les données de commande dans le paramètre de session

À partir du traitement, enregistrez les données de commande dans un paramètre de session. La commande sera utilisé dans toutes les scènes pour la même session.

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

Proposer l'ordre

Une fois que vous avez créé une commande de réservation, vous devez la présenter à l'utilisateur confirmer ou refuser. Pour ce faire, vous devez passer à une scène qui effectue une transaction de la décision.

Créer une scène de décision de transaction

Dans l'onglet Scenes (Scènes), ajoutez une scène nommée TransactionDecision.
Sous Remplissage de cases, cliquez sur + pour ajouter un emplacement.
Sous Sélectionner un type, choisissez actions.type.TransactionDecisionValue. le type d'emplacement.
Dans le champ "Nom de l'emplacement", attribuez le nom TransactionDecision à l'emplacement.
Cochez la case Personnaliser l'écriture de la valeur de l'emplacement (activée par défaut).
Sous Configurer l'emplacement, sélectionnez Utiliser un paramètre de session dans le menu déroulant.
Sous Configurer l'emplacement,saisissez le nom du paramètre de session utilisé pour enregistrer la commande dans le champ de texte (par exemple, $session.params.order).
Cliquez sur Enregistrer.

Pour tenter de remplir un emplacement TransactionDecisionValue, l'Assistant lance une expérience intégrée dans laquelle le Order que vous avez transmis est affiché directement sur une "fiche d'aperçu du panier". L'utilisateur peut dire "planifier la réservation", refuser la transaction, ou une demande de modification des détails de la réservation.

À ce stade, l'utilisateur peut également demander à modifier la commande. Dans ce cas, vous doit s'assurer que votre traitement peut traiter les demandes de modification de commande terminer l’expérience d’assemblage du chariot.

Gérer le résultat de la décision liée à la transaction

Lorsqu'un emplacement TransactionDecisionValue est rempli, la réponse de l'utilisateur à la est stockée dans un paramètre de session. Cette valeur contient les éléments suivants:

ORDER_ACCEPTED,
ORDER_REJECTED
CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT.

Pour gérer un résultat de décision de transaction:

Dans l'onglet Scenes (Scènes), sélectionnez la scène TransactionDecision que vous venez de créer.
Sous Condition, cliquez sur + pour ajouter une condition.
Dans le champ de texte, saisissez la syntaxe de condition suivante pour vérifier la valeur condition de réussite:
```
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
```
Pointez sur la condition que vous venez d'ajouter, puis cliquez sur la flèche vers le haut pour la placer avant if scene.slots.status == "FINAL".

Activez l'option Send invites (Envoyer des invites) et fournissez une invite simple pour avertir l'utilisateur. que leur réservation est effectuée:

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

Sous Transition, sélectionnez End conversation (Terminer la conversation) pour mettre fin à la conversation.
Sous Condition, cliquez sur + pour ajouter une condition.

Dans le champ de texte, saisissez la syntaxe de condition suivante pour vérifier la valeur conditions d'échec:

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

Pointez sur la condition que vous venez d'ajouter, puis cliquez sur la flèche vers le haut pour la placer avant if scene.slots.status == "FINAL".
Activez l'option Send invites (Envoyer des invites) et fournissez une invite simple pour indiquer à l'utilisateur que commande a été refusée:
```
candidates:
  - first_simple:
      variants:
        - speech: Looks like you don't want to set up a reservation. Goodbye.
```
Sous Transition, sélectionnez End conversation (Terminer la conversation) pour mettre fin à la conversation.
Sélectionnez la condition else if scene.slots.status == "FINAL".

Activez l'option Send invites (Envoyer des invites) et fournissez une invite simple pour avertir l'utilisateur. s'il n'est pas en mesure d'effectuer une transaction:

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

Sous Transition, sélectionnez End conversation (Terminer la conversation) pour mettre fin à la conversation. si un utilisateur n'est pas en mesure d'effectuer des transactions.

Finaliser la réservation et envoyer un reçu

Lorsque l'emplacement TransactionDecisionValue renvoie le résultat ORDER_ACCEPTED, vous devez effectuer immédiatement le traitement requis pour planifier (par exemple, la conserver dans votre propre base de données).

Envoyez une réponse simple pour poursuivre la conversation. L'utilisateur reçoit une "fiche de reçu réduite" ainsi que votre réponse.

Pour envoyer une mise à jour initiale de commande:

Dans l'onglet Scenes (Scènes), sélectionnez votre scène TransactionDecision.

Sous Condition, sélectionnez la condition qui vérifie le résultat de réussite. ORDER_ACCEPTED:

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

Pour cette condition, activez l'option Call your webhook (Appeler votre webhook) et indiquez un intent. nom du gestionnaire, tel que update_order.

Dans votre code webhook, ajoutez un gestionnaire d'intent pour envoyer une mise à jour de la commande initiale:

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

Envoyer des mises à jour de commande

L'état de la réservation change au cours de sa durée de vie. Envoyer à l'utilisateur des ordres de réservation à l'aide de requêtes HTTP PATCH à l'API Orders, contenant l'état et les détails de la commande.

Configurer des requêtes asynchrones dans Orders API

Les requêtes de mise à jour de commandes envoyées à Orders API sont autorisées par un accès à partir d'un jeton d'accès. Pour valider une mise à jour de commande dans Orders API, téléchargez un fichier JSON la clé de compte de service associée à votre projet dans la console Actions, puis la clé la clé du compte de service pour un jeton de support pouvant être transmis En-tête Authorization de la requête HTTP.

Pour récupérer la clé de votre compte de service, procédez comme suit:

Dans la console Google Cloud : accédez à Menu ▾ > API et Services > Identifiants > Créer des identifiants > Clé de compte de service :
Sous Compte de service, sélectionnez Nouveau compte de service.
Définissez le compte de service sur service-account.
Définissez Rôle sur Projet > Propriétaire.
Définissez le type de clé sur JSON.
Sélectionnez Créer.
Une clé de compte de service JSON privée sera téléchargée sur votre ordinateur local.

Dans votre code de mise à jour des commandes, échangez votre clé de service contre un jeton de support. à l'aide de la bibliothèque cliente des API Google "https://www.googleapis.com/auth/actions.order.developer". Vous trouverez les étapes et exemples d'installation dans la bibliothèque cliente de l'API Page GitHub

Référencer order-update.js dans notre exemple Node.js pour un exemple d'échange de clés.

Envoyer des mises à jour de commande

Après avoir échangé votre clé de compte de service contre un jeton de support OAuth, envoyez les mises à jour de commandes en tant que requêtes PATCH autorisées à l'API Orders

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

Indiquez les en-têtes suivants dans votre requête:

"Authorization: Bearer token" par le jeton de support OAuth contre laquelle vous avez échangé votre clé de compte de service.
"Content-Type: application/json".

La requête PATCH doit utiliser un corps JSON au format suivant:

{ "orderUpdate": OrderUpdate }

OrderUpdate comporte les champs de niveau supérieur suivants:

updateMask : champs de la commande que vous mettez à jour. Pour mettre à jour l'état de la réservation, définissez la valeur sur reservation.status, reservation.userVisibleStatusLabel.
order : contenu de la mise à jour. Si vous mettez à jour contenu de la réservation, définissez sa valeur sur l'objet Order mis à jour. Si vous ne faites que mettre à jour l'état de la réservation (par exemple, "PENDING" à "FULFILLED"), l'objet contient les champs suivants:
- merchantOrderId : ID que vous avez défini dans l'objet Order.
- lastUpdateTime : code temporel de cette mise à jour.
- purchase : objet contenant les éléments suivants : <ph type="x-smartling-placeholder">
  - status : état de la commande (ReservationStatus). tel que "CONFIRMED" ou "CANCELLED".
  - userVisibleStatusLabel : libellé visible par l'utilisateur fournissant des informations sur l'état de la commande, par exemple "Votre réservation est confirmée".
userNotification (facultatif) – A userNotification qui peut s'afficher sur l'appareil de l'utilisateur lors de l'envoi de cette mise à jour. Remarque que l'inclusion de cet objet ne garantit pas l'affichage d'une notification l'appareil de l'utilisateur.

L'exemple de code suivant montre un exemple de OrderUpdate qui met à jour le l'état de la commande de réservation sur 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}`);
}

Définir l'état de la réservation

ReservationStatus de la mise à jour d'une commande doit décrire l'état actuel de l'ordonnance. Dans les order.ReservationStatus de votre mise à jour , utilisez l'une des valeurs suivantes:

PENDING : la réservation a été créée. par votre action, mais nécessite un traitement supplémentaire sur votre backend.
CONFIRMED : la réservation est confirmée dans votre backend de planification.
CANCELLED : l'utilisateur a annulé sa réservation.
FULFILLED : la réservation de l'utilisateur a été réalisée par le service.
CHANGE_REQUESTED : l'utilisateur a demandé à modifier la réservation. Cette modification est en cours de traitement.
REJECTED - Si vous n'avez pas pu traiter confirmer la réservation.

Envoyez des notifications de commande pour chaque état pertinent pour votre réservation. Par exemple, si votre réservation nécessite un traitement manuel pour confirmer la réservation après sa demande, envoyer une mise à jour de la commande PENDING jusqu'au qu'un traitement supplémentaire est effectué. Toutes les réservations ne nécessitent pas toutes les valeurs d'état.

Tester votre projet

Lorsque vous testez votre projet, vous pouvez activer le mode bac à sable dans la console Actions pour tester votre action sans facturer de mode de paiement. Pour activer le mode bac à sable, procédez comme suit:

Dans la console Actions, cliquez sur Test (Tester) dans le menu de navigation.
Cliquez sur Paramètres.
Activez l'option Bac à sable de développement.

Pour les transactions physiques, vous pouvez également définir le champ isInSandbox sur true dans votre échantillon. Cette action équivaut à activer le paramètre "Mode bac à sable" dans la console Actions. Pour voir un extrait de code qui utilise isInSandbox, consultez la dans la section Envoyer des informations sur la commande.

Dépannage

Si vous rencontrez des problèmes lors des tests, consultez notre procédure de dépannage. pour les transactions.