Aktionsanfragen bearbeiten

Wie im Abschnitt Aktionen deklarieren beschrieben, sendet Google bei der Interaktion eines Nutzers mit einer In-App-Aktion eine HTTP-Anfrage an eine in der Aktion deklarierte URL.

Im folgenden Beispiel wird einer E-Mail zu einer Spesenabrechnung die 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, in der die Bestätigung erfasst wird. 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

Auf dem Rest dieser Seite wird beschrieben, was der Dienst unter https://your-domain.com/approve?expenseId=abc123 tun muss, um die Aktion ordnungsgemäß zu verarbeiten. Dazu zählen:

  • Anfrage verifizieren
  • Nutzlast verarbeiten
  • Antwortcode zurückgeben

Schritt 1: Anfrage bestätigen

Der Dienst unter https://your-domain.com/approve?expenseId=abc123 sollte Folgendes prüfen:

Der User-Agent für alle Aktionsanfragen 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 Aktion wie in den URL-Parametern angegeben sowie zusätzliche Informationen verarbeiten, die über den Nutzer erfasst wurden.

Zusätzliche Informationen des Nutzers befinden sich im Text der Anfrage und werden mit der Codierung x-www-form-urlecoded codiert. Die Informationen werden in Eigenschaften festgelegt, deren Namen den Eigenschaften von Aktion entsprechen. ConfirmAction hat beispielsweise die Eigenschaft confirmed.

Schritt 3: Antwortcode zurückgeben

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

Antwortcode Testgruppe
400 (Bad Request) Google schlägt die Aktion fehl.
401 (Unauthorized) Google schlägt die Aktion nicht vor.
404 (Nicht gefunden) Google schlägt die Aktion nicht vor.
408 (Zeitüberschreitung bei Anfrage) Google wird es später noch einmal versuchen.

Im Falle eines dauerhaften Fehlers teilt Google dem Nutzer mit, dass die Aktion fehlgeschlagen ist und er die alternativen Anweisungen in der E-Mail befolgen soll.

Weiterführende Literatur