Wie im Abschnitt Aktionen angeben 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 eine ConfirmAction
-Schaltfläche 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 aufgezeichnet 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
Im Folgenden wird beschrieben, was der Dienst unter https://your-domain.com/approve?expenseId=abc123
tun muss, um die Aktion ordnungsgemäß auszuführen. Dazu zählen:
- Anfrage verifizieren
- Nutzlast verarbeiten
- Antwortcode zurückgeben
Schritt 1: Anfrage prüfen
Der Dienst unter https://your-domain.com/approve?expenseId=abc123
wird empfohlen, Folgendes zu prüfen:
- Limited Use Access Token (Zugriffstoken mit begrenzter Verwendung) – zum Schutz vor Replay-Angriffen.
- User-Agent: Damit lässt sich überprüfen, ob die Anfrage von Google stammt.
- Bearer Token (Inhabertoken): Damit wird garantiert, dass die von Google stammende Anfrage auch wirklich an den Dienst gerichtet ist.
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 und zusätzlich über den Nutzer erfasste Informationen verarbeiten.
Zusätzliche Nutzerinformationen befinden sich im Text der Anfrage und sind mit der x-www-form-urlecoded-Codierung codiert. Die Informationen werden in Eigenschaften festgelegt, deren Namen den Eigenschaften von Aktion entsprechen. ConfirmAction hat beispielsweise das Attribut 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 | Behandlung |
---|---|
400 (Bad Request) | Google schlägt die Aktion fehl. |
401 (Unauthorized) | Google schlägt die Aktion fehl. |
404 (Nicht gefunden) | Google schlägt die Aktion fehl. |
408 (Zeitüberschreitung bei Anfrage) | Google versucht es später noch einmal. |
Tritt der Fehler dauerhaft auf, teilt Google dem Nutzer mit, dass die Aktion fehlgeschlagen ist und dass er einer alternativen Anleitung in der E-Mail folgen soll.