Gestire le richieste di azione

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 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 invia una richiesta HTTP al tuo servizio, registrando 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 in corso…
  • Elaborazione del payload
  • Restituzione di un codice di risposta

Passaggio 1: verifica la richiesta

Ti consigliamo di chiedere al servizio all'indirizzo https://your-domain.com/approve?expenseId=abc123 di verificare quanto segue:

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 dell'URL, nonché le informazioni aggiuntive raccolte dall'utente.

Le informazioni aggiuntive dell'utente si trovano nel corpo della richiesta e sono codificate utilizzando il formato x-www-form-urlencoded. 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 elabora e registra correttamente l'azione, restituisci il codice di risposta 200 (OK). Puoi utilizzare i seguenti codici di risposta in situazioni di errore:

Codice di risposta Trattamento
400 (Richiesta errata) Google contrassegna l'azione come non riuscita.
401 (Non autorizzato) Google contrassegna l'azione come non riuscita.
404 (Destinazione non trovata) Google contrassegna l'azione come non riuscita.
408 (timeout della richiesta) Google riprova più tardi.

In caso di errori permanenti, Google informa l'utente che l'azione non è andata a buon fine e che deve seguire le istruzioni alternative riportate nell'email.

Per approfondire