Obsługa żądań działań

Jak opisano 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 z raportem wydatków:

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

<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, które zarejestruje potwierdzenie. Twoja usługa otrzyma 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 dalszej części tej strony opisujemy, co musi zrobić usługa pod adresem https://your-domain.com/approve?expenseId=abc123, aby prawidłowo obsłużyć działanie. Obejmuje to m.in.:

• weryfikowanie żądania,
• przetwarzanie ładunku,
• zwracanie kodu odpowiedzi.

Krok 1. Zweryfikuj żądanie

Usługa pod adresem https://your-domain.com/approve?expenseId=abc123 powinna sprawdzić:

• token dostępu do ograniczonego użytku – aby chronić przed atakami typu replay;
• klienta użytkownika – aby upewnić się, że żądanie pochodzi od Google;
• token okaziciela – aby zagwarantować, że żądanie pochodzące od Google jest przeznaczone dla usługi.

Klient użytkownika w przypadku wszystkich żądań działania to Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).

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

Krok 2. Przetwórz działanie

Usługa powinna przetworzyć działanie zgodnie z parametrami adresu URL oraz dodatkowymi informacjami zebranymi od użytkownika.

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

Krok 3. Zwróć kod odpowiedzi

Gdy usługa przetworzy i zarejestruje działanie, powinna zwrócić kod odpowiedzi 200 (OK). W sytuacjach błędów można użyć tych kodów odpowiedzi:

W przypadku trwałego błędu Google poinformuje użytkownika, że działanie nie powiodło się, i że powinien postępować zgodnie z instrukcjami w e-mailu.

Dodatkowe informacje

• Zabezpieczanie działań