Traiter les demandes d'action

Comme décrit dans Déclarer des actions, lorsqu'un utilisateur interagit avec une action dans l'application, Google envoie une requête HTTP à une URL déclarée dans l'action.

L'exemple suivant ajoute un bouton ConfirmAction à un e-mail concernant une note de frais :

JSON-LD

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "EmailMessage",
  "potentialAction": {
    "@type": "ConfirmAction",
    "name": "Approve Expense",
    "handler": {
      "@type": "HttpActionHandler",
      "url": "https://myexpenses.com/approve?expenseId=abc123"
    }
  },
  "description": "Approval request for John's $10.13 expense for office supplies"
}
</script>

Microdonnées

<div itemscope itemtype="http://schema.org/EmailMessage">
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/ConfirmAction">
    <meta itemprop="name" content="Approve Expense"/>
    <div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <link itemprop="url" href="https://myexpenses.com/approve?expenseId=abc123"/>
    </div>
  </div>
  <meta itemprop="description" content="Approval request for John's $10.13 expense for office supplies"/>
</div>

Lorsque l'utilisateur clique sur le bouton, Google envoie une requête HTTP à votre service pour enregistrer la confirmation. Votre service reçoit la requête HTTP suivante de Google :

POST /approve?expenseId=abc123 HTTP/1.1
Host: your-domain.com
Authorization: Bearer AbCdEf123456
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)

confirmed=Approved

Le reste de cette page décrit ce que le service à l'adresse https://your-domain.com/approve?expenseId=abc123 doit faire pour gérer correctement l'action. et que vous voulez :

  • Vérification de la demande
  • Traiter la charge utile
  • Renvoyer un code de réponse

Étape 1 : Vérifiez la demande

Nous recommandons au service https://your-domain.com/approve?expenseId=abc123 de vérifier les points suivants :

L'user-agent pour toutes les demandes d'action est Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).

Si toutes les vérifications sont concluantes, le service peut passer à l'étape suivante.

Étape 2 : Traitez l'action

Le service doit traiter l'action comme spécifié dans les paramètres d'URL, ainsi que les informations supplémentaires collectées auprès de l'utilisateur.

Les informations supplémentaires fournies par l'utilisateur se trouvent dans le corps de la requête et sont encodées au format x-www-form-urlencoded. Les informations sont définies dans des propriétés dont les noms correspondent à ceux des propriétés de l'action. Par exemple, ConfirmAction possède la propriété confirmed.

Étape 3 : Renvoyez un code de réponse

Une fois que le service a traité et enregistré l'action, renvoyez le code de réponse 200 (OK). Vous pouvez utiliser les codes de réponse suivants en cas d'erreur :

Code de réponse Traitement
400 (Requête incorrecte) Google marque l'action comme ayant échoué.
401 (Opération non autorisée) Google marque l'action comme ayant échoué.
404 (Fichier introuvable) Google marque l'action comme ayant échoué.
408 (Délai avant expiration de la requête) Google réessaie plus tard.

En cas d'échec permanent, Google informe l'utilisateur que l'action a échoué et qu'il doit suivre d'autres instructions dans l'e-mail.

Documentation complémentaire