Gestire le richieste di azione

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, un pulsante ConfirmAction viene aggiunto 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 di https://your-domain.com/approve?expenseId=abc123 per gestire correttamente l'azione. È incluso quanto segue:

  • Verifica della richiesta in corso...
  • Elaborazione del payload in corso
  • Restituzione di un codice di risposta

Passaggio 1: verifica la richiesta

Consigliamo al servizio all'indirizzo https://your-domain.com/approve?expenseId=abc123 di controllare:

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ò andare al passaggio successivo.

Passaggio 2: elabora l'azione

Il servizio deve elaborare l'azione come specificato nei parametri URL, nonché informazioni aggiuntive raccolte dall'utente.

Le informazioni aggiuntive dell'utente risiedono nel corpo della richiesta e sono codificate utilizzando la codifica x-www-form-urlecoded. Le informazioni vengono impostate in proprietà i cui nomi corrispondono alle proprietà 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 l'azione, dovrebbe restituire un codice di risposta 200 (OK). I seguenti codici di risposta possono essere utilizzati in situazioni di errore:

Codice di risposta Trattamento
400 (Richiesta errata) Google non eseguirà l'azione.
401 (Autorizzazione non autorizzata) 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 permanente, Google comunicherà all'utente che l'azione non è riuscita e che l'utente deve seguire istruzioni alternative all'interno dell'email.

Per approfondire

di Gemini Advanced.