Obsługa żądań działań

Zgodnie z opisem w sekcji Deklarowanie działań, gdy użytkownik wejdzie w interakcję z działaniem w aplikacji, Google wysyła żądanie HTTP na adres URL zadeklarowany w działaniu.

Poniższy przykład dodaje 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 z potwierdzeniem. Twoja usługa otrzymuje to żądanie HTTP od 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

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

  • Weryfikuję prośbę
  • Przetwarzanie ładunku
  • Zwracanie kodu odpowiedzi

Krok 1. Zweryfikuj prośbę

Zachęcamy do sprawdzenia usługi pod numerem https://your-domain.com/approve?expenseId=abc123:

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 zostaną zaliczone, usługa może przejść do następnego kroku.

Krok 2. Przetwórz działanie

Usługa powinna przetwarzać działanie określone w parametrach adresu URL, a także 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 we właściwościach, których nazwy odpowiadają właściwościom Action (Działanie). Na przykład ConfirmAction (Potwierdź działanie) ma właściwość confirmed.

Krok 3. Zwróć kod odpowiedzi

Po przetworzeniu i zarejestrowaniu działania przez usługę powinna zwrócić kod odpowiedzi 200 (OK). W przypadku błędu można użyć tych kodów odpowiedzi:

Kod odpowiedzi Grupa eksperymentalna
400 (Nieprawidłowe żądanie) Google nie powiedzie się.
401 (Brak autoryzacji) Google nie powiedzie się.
404 (nie znaleziono) Google nie powiedzie się.
408 (Przekroczenie limitu czasu żądania) Google spróbuje ponownie później.

W przypadku trwałej awarii Google powiadomi użytkownika, że czynność nie powiodła się, i że powinien wykonać alternatywne instrukcje zawarte w e-mailu.

Dalsza lektura

.