Come descritto nella sezione Dichiarazione di azioni, quando un utente interagisce con un'Azione in-app, Google invia una richiesta HTTP a un URL dichiarato nell'azione.
Nell'esempio seguente viene aggiunto un pulsante ConfirmAction a un'email relativa a una nota 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 emette una richiesta HTTP al servizio con la conferma della 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 della pagina descrive cosa deve fare il servizio all'indirizzo https://your-domain.com/approve?expenseId=abc123 per gestire correttamente l'azione. È incluso quanto segue:
- Verificare la richiesta
- Elaborazione del payload
- Restituire un codice di risposta
Passaggio 1: verifica la richiesta
Consigliamo al servizio all'indirizzo https://your-domain.com/approve?expenseId=abc123 di verificare:
- Limitato token di accesso: per proteggere da attacchi di ripetizione.
- User agent: per assicurarsi che la richiesta provenga da Google.
- Token di connessione: per garantire che la richiesta proveniente da Google sia destinata al servizio.
Lo user agent per tutte le richieste di azione è 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 sono codificate utilizzando la codifica x-www-form-urlecoded. Le informazioni vengono impostate nelle proprietà i cui nomi corrispondono alle proprietà dell'Azione. Ad esempio, ConfirmAction ha la proprietà confirmed.
Passaggio 3: restituisci un codice di risposta
Una volta che il servizio ha elaborato e registrato l'azione, dovrebbe restituire un codice di risposta 200 (OK). In situazioni di errore, è possibile utilizzare i seguenti codici di risposta:
| Codice di risposta | Trattamento |
|---|---|
| 400 (Richiesta non valida) | Google non supererà l'azione. |
| 401 (Non autorizzato) | Google non supererà l'azione. |
| 404 (Destinazione non trovata) | Google non supererà l'azione. |
| 408 (Timeout della richiesta) | Google riproverà più tardi. |
In caso di errore permanente, Google comunicherà all'utente che l'azione non è riuscita e che l'utente deve seguire istruzioni alternative all'interno dell'email.