Aktionsanfragen bearbeiten

Wie unter Aktionen deklarieren beschrieben, sendet Google, wenn ein Nutzer mit einer In-App-Aktion interagiert, eine HTTP-Anfrage an eine in der Aktion deklarierte URL.

Im folgenden Beispiel wird einer E-Mail mit einem Spesenbericht eine Schaltfläche ConfirmAction hinzugefügt:

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>

Mikrodaten

<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>

Wenn der Nutzer auf die Schaltfläche klickt, wird von Google eine HTTP-Anfrage an Ihren Dienst gesendet, um die Bestätigung zu erfassen. Ihr Dienst empfängt die folgende HTTP-Anfrage von 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

Im restlichen Teil dieser Seite wird beschrieben, was der Dienst bei https://your-domain.com/approve?expenseId=abc123 tun muss, um die Aktion richtig zu verarbeiten. Dazu zählen:

  • Anfrage verifizieren
  • Nutzlast verarbeiten
  • Antwortcode zurückgeben

Schritt 1: Anfrage prüfen

Der Dienstleister unter https://your-domain.com/approve?expenseId=abc123 wird gebeten, Folgendes zu prüfen:

Der User-Agent für alle Action-Anfragen ist Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).

Wenn alle Prüfungen bestanden wurden, kann der Dienst mit dem nächsten Schritt fortfahren.

Schritt 2: Aktion verarbeiten

Der Dienst sollte die in den URL-Parametern angegebene Aktion sowie zusätzliche vom Nutzer erhobene Informationen verarbeiten.

Zusätzliche Informationen vom Nutzer befinden sich im Textkörper der Anfrage und werden mit der Codierung x-www-form-urlecoded codiert. Die Informationen werden in Properties festgelegt, deren Namen den Properties von „Action“ entsprechen. ConfirmAction hat beispielsweise die Property confirmed.

Schritt 3: Antwortcode zurückgeben

Sobald der Dienst die Aktion verarbeitet und aufgezeichnet hat, sollte er den Antwortcode 200 (OK) zurückgeben. Die folgenden Antwortcodes können in Fehlersituationen verwendet werden:

Antwortcode Testgruppe
400 (Bad Request) Google lehnt die Aktion ab.
401 (Unauthorized) Google lehnt die Aktion ab.
404 (Nicht gefunden) Google lehnt die Aktion ab.
408 (Request Timeout) Google versucht es später noch einmal.

Bei einem dauerhaften Fehler wird der Nutzer von Google darüber informiert, dass die Aktion fehlgeschlagen ist und dass er der alternativen Anleitung in der E-Mail folgen soll.

Weiterführende Literatur