كما هو موضّح في بيان الإجراءات، عندما يتفاعل مستخدم مع إجراء داخل التطبيق، ترسل Google طلب 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>
عندما ينقر المستخدم على الزرّ، ستصدر Google طلب HTTP من Google إلى خدمتك، ويتم تسجيل التأكيد. تتلقّى خدمتك طلب HTTP التالي من 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
يصف الجزء المتبقي من هذه الصفحة الإجراءات التي يجب على الخدمة في https://your-domain.com/approve?expenseId=abc123 اتّخاذها لمعالجة الإجراء بشكل صحيح. يشمل ذلك ما يلي:
- جارٍ التحقّق من الطلب
- معالجة الحمولة
- عرض رمز استجابة
الخطوة 1: التحقُّق من الطلب
ننصح الخدمة في "https://your-domain.com/approve?expenseId=abc123" بالتحقّق مما يلي:
- رمز الدخول المحدود للاستخدام - للحماية من هجمات إعادة التشغيل.
- وكيل المستخدم: للتأكّد من أنّ الطلب وارد من Google
- الرمز المميّز للحامل: لضمان أنّ الطلب الوارد من Google مخصّص للخدمة.
وكيل المستخدم لجميع طلبات الإجراءات هو "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)".
في حال اجتياز جميع عمليات التحقّق، يمكن للخدمة المتابعة إلى الخطوة التالية.
الخطوة 2: معالجة الإجراء
ويجب أن تعالج الخدمة الإجراء على النحو المحدّد في مَعلمات عناوين URL إلى جانب المعلومات الإضافية التي يتمّ جمعها من المستخدِم.
تتوفّر معلومات إضافية من المستخدم في نص الطلب، ويتم ترميزها باستخدام الترميز x-www-form-urlecoded. يتم تعيين المعلومات في الخصائص التي تتوافق أسماؤها مع خصائص الإجراء. على سبيل المثال، تحتوي الدالة ConfirmAction على السمة confirmed.
الخطوة 3: عرض رمز الاستجابة
بعد معالجة الخدمة وتسجيل الإجراء بنجاح، من المفترض أن تعرض رمز الاستجابة 200 (OK). يمكن استخدام رموز الاستجابة التالية في حالات الخطأ:
| رمز الاستجابة | العلاج |
|---|---|
| 400 (طلب غير صالح) | ستفشل Google في تنفيذ الإجراء. |
| 401 (غير مصرح به) | ستفشل Google في تنفيذ الإجراء. |
| 404 (لم يتم العثور عليها) | ستفشل Google في تنفيذ الإجراء. |
| 408 (انتهت مهلة الطلب) | سيعيد Google المحاولة لاحقًا. |
وفي حال تعذُّر إكمال العملية بشكل دائم، ستخبر Google المستخدم بتعذُّر تنفيذ الإجراء وأنّه عليه اتّباع التعليمات البديلة الموجودة في الرسالة الإلكترونية.