Como se describe en Cómo declarar acciones, cuando un usuario interactúa con una acción integrada en la aplicación, 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, Google enviará una solicitud HTTP a tu servicio para 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 el servicio en https://your-domain.com/approve?expenseId=abc123 debe hacer para controlar la acción correctamente. Esto incluye lo siguiente:
- Verifica la solicitud
- Procesa la carga útil
- Cómo mostrar un código de respuesta
Paso 1: Verifica la solicitud
Se recomienda que el servicio de https://your-domain.com/approve?expenseId=abc123 verifique lo siguiente:
- Token de acceso de uso limitado: Para protegerte contra ataques de repetición.
- Usuario-agente: Para asegurarte de que la solicitud provenga de Google.
- Token de portador: Garantiza que la solicitud que proviene de Google esté destinada al servicio.
El usuario-agente de todas las solicitudes de Action 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 siguiente paso.
Paso 2: Procesa la acción
El servicio debe procesar la acción como se especifica 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 con las propiedades de Action. Por ejemplo, ConfirmAction tiene la propiedad confirmed.
Paso 3: Devuelve un código de respuesta
Una vez que el servicio procese y registre 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 rechazará la acción. |
| 401 (no está autorizado) | Google rechazará la acción. |
| 404 (No encontrado) | Google rechazará la acción. |
| 408 (se agotó el tiempo de espera de la solicitud) | Google volverá a intentarlo más tarde. |
En caso de falla permanente, Google le informará al usuario que la acción falló y que debe seguir las instrucciones alternativas que se indican en el correo electrónico.