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 la part 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 l'action correctement. Par exemple :
- Vérifier la requête
- Traiter la charge utile
- Renvoyer un code de réponse
Étape 1: Vérifiez la requête
Nous vous recommandons de vérifier les points suivants pour le service proposé par https://your-domain.com/approve?expenseId=abc123:
- Jeton d'accès limité à usage limité : pour une protection contre les attaques par rejeu.
- User-agent : pour s'assurer que la requête provient de Google.
- Bearer Token (Jeton de support) : pour garantir que la requête provenant de Google est destinée au service.
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.
D'autres informations provenant de l'utilisateur se trouvent dans le corps de la requête. Elles sont encodées selon le format x-www-form-urlecoded. Les informations sont définies dans les 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 le 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 n'effectuera pas cette action. |
| 401 (Opération non autorisée) | Google n'effectuera pas cette action. |
| 404 (Fichier introuvable) | Google n'effectuera pas cette action. |
| 408 (Expiration du délai de la requête) | Google réessaiera plus tard. |
En cas d'échec permanent, Google informe l'utilisateur que l'action a échoué et qu'il doit suivre d'autres instructions contenues dans l'e-mail.