Gérer les requêtes d'action

Comme indiqué dans la section 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 sur 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 et enregistre 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 de https://your-domain.com/approve?expenseId=abc123 doit faire pour gérer cette action correctement. Ce bloc inclut les éléments suivants :

  • Vérifier la requête
  • Traiter la charge utile
  • Renvoyer un code de réponse

Étape 1: Validez la demande

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

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

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

Étape 2: Traiter l'action

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

Des informations supplémentaires provenant de l'utilisateur se trouvent dans le corps de la requête. Elles sont encodées selon l'encodage x-www-form-urlecoded. Les informations sont définies dans des propriétés dont les noms correspondent aux propriétés de l'action. Par exemple, ConfirmAction a la propriété confirmed.

Étape 3: Renvoyez un code de réponse

Une fois que le service a traité et enregistré l'action, il doit renvoyer un code de réponse 200 (OK). Les codes de réponse suivants peuvent être utilisés en cas d'erreur:

Code de réponse Traitement
400 (Requête incorrecte) Google échouera à l'action.
401 (Opération non autorisée) Google échouera à l'action.
404 (Fichier introuvable) Google échouera à l'action.
408 (Expiration du délai de la requête) Google réessayera plus tard.

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

Documentation complémentaire