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, Google emitirá una solicitud HTTP a tu servicio, que 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 en https://your-domain.com/approve?expenseId=abc123 para controlar la acción correctamente. Esto incluye lo siguiente:
- Verificar la solicitud
- Procesar la carga útil
- Mostrar un código de respuesta
Paso 1: Verifica la solicitud
Se recomienda que el servicio en https://your-domain.com/approve?expenseId=abc123 verifique lo siguiente:
- Token de acceso de uso limitado: Para proteger contra ataques de repetición
- Agente de usuario: Para asegurarse de que la solicitud provenga de Google
- Token de portador: Para garantizar que la solicitud que proviene de Google esté destinada al servicio
El agente de usuario para todas las solicitudes de acción es Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).
Si todas las verificaciones se realizan correctamente, el servicio puede continuar con el siguiente paso.
Paso 2: Procesa la acción
El servicio debe procesar la acción según se especifica en los parámetros de la 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 la acción. Por ejemplo, ConfirmAction tiene la propiedad confirmed.
Paso 3: Muestra un código de respuesta
Una vez que el servicio procese y registre la acción correctamente, debe 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 instrucciones alternativas dentro del correo electrónico.