Como se describe en Cómo declarar acciones, cuando un usuario interactúa con una Acción integrada 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 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
- Procesamiento de la carga útil
- Cómo devolver 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 protegerse contra ataques de repetición.
- User Agent: 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 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 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 se encuentra 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: Devuelve un código de respuesta
Una vez que el servicio procese y registre la acción correctamente, debe devolver un código de respuesta 200 (OK). En situaciones de error, se pueden usar los siguientes códigos de respuesta:
| 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 encuentran en el correo electrónico.