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:
- Token dostępu ograniczonego użycia – służy do ochrony przed atakami typu replay.
- Klient użytkownika – aby mieć pewność, że żądanie pochodzi od Google.
- Token okaziciela – aby zagwarantować, że żądanie pochodzące od Google jest przeznaczone dla danej usługi.
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.