Obsługa żądań działań

Jak opisano w artykule Oświadczanie działań, gdy użytkownik wchodzi w interakcję z działaniem w aplikacji, Google wysyła żądanie HTTP do adresu URL zadeklarowanego w tym działaniu.

W tym przykładzie dodajemy do e-maila dotyczącego raportu wydatków przycisk ConfirmAction:

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>

Mikrodane

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

Gdy użytkownik kliknie przycisk, Google wyśle do Twojej usługi żądanie HTTP, aby potwierdzić. Twoja usługa otrzymuje od Google to żądanie HTTP:

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

W pozostałości tej strony opisano, co usługa na adresie https://your-domain.com/approve?expenseId=abc123 musi zrobić, aby poprawnie obsłużyć działanie. Obejmuje to m.in.:

  • Weryfikowanie prośby
  • Przetwarzanie ładunku
  • Zwracanie kodu odpowiedzi

Krok 1. Sprawdź prośbę

Użytkownik usługi https://your-domain.com/approve?expenseId=abc123 powinien sprawdzić:

Klient użytkownika dla wszystkich żądań akcji to Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).

Jeśli wszystkie testy zakończą się powodzeniem, usługa może przejść do następnego kroku.

Krok 2. Przetwarzanie działania

Usługa powinna przetwarzać działanie określone w parametrach adresu URL oraz dodatkowe informacje zebrane od użytkownika.

Dodatkowe informacje od użytkownika znajdują się w ciele żądania i są zakodowane za pomocą kodowania x-www-form-urlecoded. Informacje są ustawiane w elementach, których nazwy odpowiadają elementom działania. Na przykład ConfirmAction ma właściwość confirmed.

Krok 3. Wpisz kod odpowiedzi

Gdy usługa przetworzy i zarejestruje działanie, powinna zwrócić kod odpowiedzi 200 (OK). W przypadku błędów mogą być używane te kody odpowiedzi:

Kod odpowiedzi Grupa eksperymentalna
400 (Nieprawidłowe żądanie) Google nie wykona tej czynności.
401 (brak uprawnień) Google nie wykona tej czynności.
404 (nie znaleziono) Google nie wykona tej czynności.
408 (Przekroczenie limitu czasu żądania) Google spróbuje ponownie później.

W przypadku trwałej awarii Google poinformuje użytkownika o niepowiednim działaniu i poprosi o zrealizowanie instrukcji zawartych w e-mailu.

Więcej informacji