Conforme descrito em Declarar 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
- Como processar o payload
- Como retornar um código de resposta
Etapa 1: verificar a solicitação
É recomendado que o serviço em https://your-domain.com/approve?expenseId=abc123 verifique:
- Token de acesso de uso limitado: para proteção contra ataques de repetição.
- User agent: para garantir que a solicitação vem do Google.
- Token do portador: garante que a solicitação vinda do Google seja destinada ao serviço.
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 precisa processar a ação conforme especificado nos parâmetros de URL, além das informações adicionais coletadas do usuário.
As informações adicionais do usuário residem no corpo da solicitação e são codificadas usando a codificação 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 registrado a ação, ele retornará um código de resposta 200 (OK). Os seguintes códigos de resposta podem ser usados em situações de erro:
| Código de resposta | Tratamento |
|---|---|
| 400 (Solicitação inválida) | O Google não realizará a ação. |
| 401 (Não autorizado) | O Google não realizará a ação. |
| 404 (não encontrado) | O Google não realizará a ação. |
| 408 (Tempo limite da solicitação) | O Google vai tentar novamente mais tarde. |
Em caso de falha permanente, o Google vai informar ao usuário que a ação falhou e que ele precisa seguir as instruções alternativas no e-mail.