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

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

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

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

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

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

قراءات إضافية

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

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