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 dodawany jest przycisk ConfirmAction do e-maila dotyczącego raportu wydatków:

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łej części tej strony opisano, co usługa w domenie https://your-domain.com/approve?expenseId=abc123 musi zrobić, aby prawidłowo wykonać to 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 treści żądania i są zakodowane przy użyciu kodowania x-www-form-urlecoded. Informacje są ustawiane w elementach, których nazwy odpowiadają elementom działania. Na przykład ConfirmAction (Potwierdź działanie) ma właściwość confirmed.

Krok 3. Wpisz kod odpowiedzi

Po przetworzeniu i zarejestrowaniu działania przez usługę 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 powiedzie się.
401 (Brak autoryzacji) 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, że działanie się nie powiodło, i poprosi o wykonanie instrukcji zawartych w e-mailu.

Dalsza lektura