رسیدگی به درخواست‌های اقدام

همانطور که در بخش «اعلان اقدامات» توضیح داده شد، وقتی کاربری با یک اقدام درون‌برنامه‌ای تعامل می‌کند، گوگل یک درخواست HTTP به آدرس اینترنتی (URL) اعلام‌شده در آن اقدام ارسال می‌کند.

مثال زیر یک دکمه ConfirmAction به ایمیلی در مورد گزارش هزینه اضافه می‌کند:

<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 برای مدیریت صحیح این اقدام چه کاری باید انجام دهد. این شامل موارد زیر است:

• تأیید درخواست
• پردازش بار مفید
• برگرداندن کد پاسخ

Step 1: Verify the Request

پیشنهاد می‌شود سرویس https://your-domain.com/approve?expenseId=abc123 موارد زیر را بررسی کند:

• توکن دسترسی با کاربرد محدود - برای محافظت در برابر حملات بازپخش.
• نماینده کاربر - برای اطمینان از اینکه درخواست از طرف گوگل می‌آید.
• توکن حامل - برای تضمین اینکه درخواست ارسالی از گوگل، مختص سرویس مورد نظر است.

عامل کاربری برای همه درخواست‌های Action، Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions) است.

اگر همه بررسی‌ها با موفقیت انجام شود، سرویس می‌تواند به مرحله بعدی برود.

Step 2: Process the Action

این سرویس باید عمل را مطابق با پارامترهای URL و همچنین اطلاعات اضافی جمع‌آوری‌شده از کاربر پردازش کند.

اطلاعات اضافی از کاربر در بدنه درخواست قرار دارد و با استفاده از کدگذاری x-www-form-urlecoded کدگذاری می‌شود. این اطلاعات در ویژگی‌هایی قرار می‌گیرند که نام آنها با ویژگی‌های Action مطابقت دارد. به عنوان مثال، ConfirmAction دارای ویژگی confirmed است.

Step 3: Return a Response Code

پس از اینکه سرویس با موفقیت عملیات را پردازش و ثبت کرد، باید کد پاسخ 200 (OK) را برگرداند. کدهای پاسخ زیر می‌توانند در موقعیت‌های خطا استفاده شوند:

در صورت عدم موفقیت دائمی، گوگل به کاربر اطلاع می‌دهد که اقدام ناموفق بوده و کاربر باید دستورالعمل‌های جایگزین داخل ایمیل را دنبال کند.

مطالعه بیشتر

• Securing Actions