همانطور که در بخش «اعلان اقدامات» توضیح داده شد، وقتی کاربری با یک اقدام درونبرنامهای تعامل میکند، گوگل یک درخواست HTTP به آدرس اینترنتی (URL) اعلامشده در آن اقدام ارسال میکند.
مثال زیر یک دکمه 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>
میکرودیتا
<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>
وقتی کاربر روی دکمه کلیک میکند، یک درخواست HTTP از گوگل به سرویس شما ارسال میشود و تأییدیه ثبت میشود. سرویس شما درخواست 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
ادامهی این صفحه شرح میدهد که سرویس آدرس https://your-domain.com/approve?expenseId=abc123 برای مدیریت صحیح این اقدام چه کاری باید انجام دهد. این شامل موارد زیر است:
- تأیید درخواست
- پردازش بار مفید
- برگرداندن کد پاسخ
مرحله ۱: تأیید درخواست
پیشنهاد میشود سرویس https://your-domain.com/approve?expenseId=abc123 موارد زیر را بررسی کند:
- توکن دسترسی با کاربرد محدود - برای محافظت در برابر حملات بازپخش.
- نماینده کاربر - برای اطمینان از اینکه درخواست از طرف گوگل میآید.
- توکن حامل - برای تضمین اینکه درخواست ارسالی از گوگل، مختص سرویس مورد نظر است.
عامل کاربری برای همه درخواستهای Action، Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions) است.
اگر همه بررسیها با موفقیت انجام شود، سرویس میتواند به مرحله بعدی برود.
مرحله ۲: پردازش اقدام
این سرویس باید عمل را مطابق با پارامترهای URL و همچنین اطلاعات اضافی جمعآوریشده از کاربر پردازش کند.
اطلاعات اضافی از کاربر در بدنه درخواست قرار دارد و با استفاده از کدگذاری x-www-form-urlecoded کدگذاری میشود. این اطلاعات در ویژگیهایی قرار میگیرند که نام آنها با ویژگیهای Action مطابقت دارد. به عنوان مثال، ConfirmAction دارای ویژگی confirmed است.
مرحله ۳: برگرداندن یک کد پاسخ
پس از اینکه سرویس با موفقیت عملیات را پردازش و ثبت کرد، باید کد پاسخ 200 (OK) را برگرداند. کدهای پاسخ زیر میتوانند در موقعیتهای خطا استفاده شوند:
| کد پاسخ | درمان |
|---|---|
| ۴۰۰ (درخواست نامناسب) | گوگل این اقدام را با شکست مواجه خواهد کرد. |
| ۴۰۱ (غیرمجاز) | گوگل این اقدام را با شکست مواجه خواهد کرد. |
| ۴۰۴ (یافت نشد) | گوگل این اقدام را با شکست مواجه خواهد کرد. |
| ۴۰۸ (درخواست مهلت زمانی) | گوگل بعداً دوباره امتحان خواهد کرد. |
در صورت عدم موفقیت دائمی، گوگل به کاربر اطلاع میدهد که اقدام ناموفق بوده و کاربر باید دستورالعملهای جایگزین داخل ایمیل را دنبال کند.