معالجة طلبات الإجراءات

كما هو موضّح في تعريف الإجراءات، عندما يتفاعل مستخدم مع "إجراء داخل التطبيق"، ترسل 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>

عندما ينقر المستخدم على الزر، سيتم إرسال طلب 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. يتم ضبط المعلومات في سمات تتطابق أسماؤها مع سمات Action. على سبيل المثال، يحتوي النوع ConfirmAction على السمة confirmed.

الخطوة 3: عرض رمز استجابة

بعد أن تعالج الخدمة الإجراء وتسجّله بنجاح، من المفترض أن تعرض رمز الاستجابة 200 (OK). يمكن استخدام رموز الاستجابة التالية في حالات الخطأ:

رمز الاستجابة	المجموعة التجريبية
‫400 (طلب غير صالح)	سترفض Google تنفيذ الإجراء.
‫401 (غير مصرّح به)	سترفض Google تنفيذ الإجراء.
404 (لم يتم العثور عليها)	سترفض Google تنفيذ الإجراء.
‫408 (انتهت مهلة الطلب)	ستعيد Google المحاولة لاحقًا.

في حال حدوث خطأ دائم، ستُخبر Google المستخدم بأنّ الإجراء قد تعذّر وأنّه عليه اتّباع تعليمات بديلة داخل الرسالة الإلكترونية.

محتوى إضافي للقراءة

• تأمين الإجراءات

ملاحظة: لا تزال بعض المخططات التي تستخدمها Google تخضع لعملية التوحيد القياسي في schema.org، وبالتالي قد تتغيّر في المستقبل. مزيد من المعلومات