Come descritto in Dichiarare le azioni, quando un utente interagisce con un'azione in-app, Google invia una richiesta HTTP a un URL dichiarato nell'azione.
L'esempio seguente aggiunge un pulsante ConfirmAction a un'email relativa a un report sulle spese:
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>
Microdati
<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>
Quando l'utente fa clic sul pulsante, Google invia una richiesta HTTP al tuo servizio per registrare la conferma. Il tuo servizio riceve la seguente richiesta HTTP da 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
Il resto di questa pagina descrive cosa deve fare il servizio all'indirizzo https://your-domain.com/approve?expenseId=abc123 per gestire correttamente l'azione. È incluso quanto segue:
- Verifica della richiesta
- Elaborazione del payload
- Restituire un codice di risposta
Passaggio 1: verifica la richiesta
Il servizio presso https://your-domain.com/approve?expenseId=abc123 è invitato a controllare:
- Token di accesso con utilizzo limitato: per proteggerti dagli attacchi di replay.
- User agent: per assicurarti che la richiesta provenga da Google.
- Token bearer: per garantire che la richiesta proveniente da Google sia destinata al servizio.
Lo user agent per tutte le richieste di azioni è Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).
Se tutti i controlli vengono superati, il servizio può procedere al passaggio successivo.
Passaggio 2: elabora l'azione
Il servizio deve elaborare l'azione come specificato nei parametri URL, nonché le informazioni aggiuntive raccolte dall'utente.
Le informazioni aggiuntive dell'utente si trovano nel corpo della richiesta e vengono codificate utilizzando la codifica x-www-form-urlecoded. Le informazioni vengono impostate in proprietà i cui nomi corrispondono a quelli di Azione. Ad esempio, ConfirmAction ha la proprietà confirmed.
Passaggio 3: restituisci un codice di risposta
Una volta che il servizio ha elaborato e registrato correttamente l'azione, deve restituire un codice di risposta 200 (OK). I seguenti codici di risposta possono essere utilizzati in caso di errori:
| Codice di risposta | Trattamento |
|---|---|
| 400 (Richiesta non valida) | Google non eseguirà l'azione. |
| 401 (non autorizzato) | Google non eseguirà l'azione. |
| 404 (Destinazione non trovata) | Google non eseguirà l'azione. |
| 408 (timeout della richiesta) | Google riproverà più tardi. |
In caso di errore permanenti, Google comunicherà all'utente che l'azione non è riuscita e che deve seguire istruzioni alternative all'interno dell'email.