Cómo controlar solicitudes de acción

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 emitirá una solicitud HTTP de Google 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 administrar la acción de manera correcta. Esto incluye lo siguiente:

  • Cómo verificar 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:

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 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 mediante 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: Devuelve un código de respuesta

Una vez que el servicio procesó y registró la acción correctamente, debería mostrar un código de respuesta 200 (OK). Los siguientes códigos de respuesta pueden utilizarse en situaciones de error:

Código de respuesta Tratamiento
400 (solicitud incorrecta) Google no podrá realizar la acción.
401 (no está autorizado) Google no podrá realizar la acción.
404 (No encontrado) Google no podrá realizar la acción.
408 (Tiempo de espera de la solicitud) Google volverá a intentarlo más tarde.

En caso de falla permanente, Google le informará al usuario que se produjo un error y que debe seguir instrucciones alternativas en el correo electrónico.

Material de lectura adicional