Como se describe en Cómo declarar acciones, cuando un usuario interactúa con una acción 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 hace clic en el botón, Google envía una solicitud HTTP a tu servicio y registra 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 de forma adecuada. Esto incluye lo siguiente:
- Verificar la solicitud
- Procesar la carga útil
- Mostrar un código de respuesta
Paso 1: Verifica la solicitud
Recomendamos que el servicio en https://your-domain.com/approve?expenseId=abc123 verifique lo siguiente:
- Tokens de acceso de uso limitado: Protege contra ataques de reproducción.
- Agente de usuario: Asegúrate de que la solicitud provenga de Google.
- Tokens de portador: Asegúrate de que la solicitud 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 el
x-www-form-urlencoded. 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
Después de que el servicio procese y registre la acción correctamente, muestra el código de respuesta 200 (OK). Puedes usar los siguientes códigos de respuesta en situaciones de error:
| Código de respuesta | Tratamiento |
|---|---|
| 400 (solicitud incorrecta) | Google marca la acción como fallida. |
| 401 (no está autorizado) | Google marca la acción como fallida. |
| 404 (No encontrado) | Google marca la acción como fallida. |
| 408 (Tiempo de espera agotado para la solicitud) | Google vuelve a intentarlo más tarde. |
En caso de fallas permanentes, Google informa al usuario que la acción falló y que debe seguir instrucciones alternativas dentro del correo electrónico.