Como se describe en Cómo declarar acciones, cuando un usuario interactúa con una Acción en la app, Google envía una solicitud HTTP a una URL declarada en la acción.
En el siguiente ejemplo, se agrega un botón ConfirmAction a un correo electrónico sobre un informe de gastos:
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>
Microdatos
<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>
Cuando el usuario haga clic en el botón, se enviará una solicitud HTTP a tu servicio y se registrará la confirmación. Tu servicio recibe la siguiente solicitud HTTP de 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
En el resto de esta página, se describe lo que debe hacer el servicio de https://your-domain.com/approve?expenseId=abc123 para procesar la acción correctamente. Esto incluye lo siguiente:
- Cómo verificar la solicitud
- Cómo procesar la carga útil
- Cómo mostrar un código de respuesta
Paso 1: Verifica la solicitud
Te recomendamos que verifiques lo siguiente en el servicio de https://your-domain.com/approve?expenseId=abc123:
- Token de acceso de uso limitado: Se usa para brindar protección contra ataques de reinyección.
- Usuario-agente: Se usa para garantizar que la solicitud provenga de Google.
- Token del portador: Se usa para garantizar que la solicitud procedente de Google esté destinada al servicio.
El usuario-agente para todas las solicitudes de acción es Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).
Si se aprueban todas las verificaciones, el servicio puede continuar con el paso siguiente.
Paso 2: Procesa la acción
El servicio debe procesar la acción según se especifique en los parámetros de URL, así como la información adicional recopilada del usuario.
La información adicional del usuario reside en el cuerpo de la solicitud y se codifica con la codificación x-www-form-urlecoded. La información se establece en propiedades cuyos nombres corresponden a las propiedades de Action. Por ejemplo, ConfirmAction tiene la propiedad confirmed.
Paso 3: Muestra un código de respuesta
Una vez que el servicio haya procesado y registrado la acción correctamente, debería mostrar un código de respuesta 200 (OK). Los siguientes códigos de respuesta se pueden usar en situaciones de error:
| Código de respuesta | Tratamiento |
|---|---|
| 400 (solicitud incorrecta) | Google no podrá completar la acción. |
| 401 (no está autorizado) | Google no podrá completar la acción. |
| 404 (No encontrado) | Google no podrá completar la acción. |
| 408 (Se agotó el tiempo de espera de la solicitud) | Google volverá a intentarlo más tarde. |
En caso de que ocurra una falla permanente, Google le indicará al usuario que la acción falló y que el usuario debe seguir las instrucciones alternativas en el correo electrónico.