Processar solicitações de ação

Conforme descrito em Declaração de ações, quando um usuário interage com uma ação no app, o Google envia uma solicitação HTTP para um URL declarado na ação.

O exemplo a seguir adiciona um botão ConfirmAction a um e-mail sobre um relatório de despesas:

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>

Microdados

<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 o usuário clicar no botão, uma solicitação HTTP será emitida do Google para seu serviço, registrando a confirmação. Seu serviço recebe a seguinte solicitação HTTP do 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

O restante desta página descreve o que o serviço em https://your-domain.com/approve?expenseId=abc123 precisa fazer para processar a ação corretamente. Isso inclui:

  • Como verificar a solicitação
  • Processamento do payload
  • Como retornar um código de resposta

Etapa 1: verificar a solicitação

Recomendamos que o serviço em https://your-domain.com/approve?expenseId=abc123 verifique:

O user agent para todas as solicitações de ação é Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).

Se todas as verificações forem aprovadas, o serviço poderá prosseguir para a próxima etapa.

Etapa 2: processar a ação

O serviço deve processar a ação conforme especificado nos parâmetros de URL, bem como nas informações adicionais coletadas do usuário.

As informações adicionais do usuário estão no corpo da solicitação e são codificadas usando x-www-form-urlecoded. As informações são definidas em propriedades com nomes que correspondem às propriedades da ação. Por exemplo, ConfirmAction tem a propriedade confirmed.

Etapa 3: retornar um código de resposta

Depois que o serviço for processado e gravado a ação, ele retornará um código de resposta 200 (OK). Os códigos de resposta a seguir podem ser usados em situações de erro:

Código de resposta Tratamento
400 (Solicitação inválida) O Google vai falhar na ação.
401 (Não autorizado) O Google vai falhar na ação.
404 (não encontrado) O Google vai falhar na ação.
408 (Tempo limite da solicitação) O Google vai tentar de novo mais tarde.

Em caso de falha permanente, o Google vai informar ao usuário que a ação falhou e que o usuário deve seguir as instruções alternativas contidas no e-mail.

Leitura adicional

.