با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
همانطور که در «اعلام کنش‌ها» توضیح داده شد، وقتی کاربر با یک اقدام درون‌برنامه تعامل می‌کند، Google یک درخواست HTTP را به نشانی اینترنتی اعلام‌شده در کنش ارسال می‌کند.
مثال زیر یک دکمه ConfirmAction را به ایمیل مربوط به گزارش هزینه اضافه می کند:
JSON-LD
<scripttype="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>
میکروداده
<divitemscopeitemtype="http://schema.org/EmailMessage">
<divitemprop="potentialAction"itemscopeitemtype="http://schema.org/ConfirmAction">
<metaitemprop="name"content="Approve Expense"/>
<divitemprop="handler"itemscopeitemtype="http://schema.org/HttpActionHandler">
<linkitemprop="url"href="https://myexpenses.com/approve?expenseId=abc123"/>
</div>
</div>
<metaitemprop="description"content="Approval request for John's $10.13 expense for office supplies"/>
</div>
هنگامی که کاربر روی دکمه کلیک می کند، یک درخواست HTTP از Google برای سرویس شما صادر می شود و تأییدیه را ثبت می کند. سرویس شما درخواست HTTP زیر را از Google دریافت می کند:
POST/approve?expenseId=abc123HTTP/1.1Host:your-domain.comAuthorization:Bearer AbCdEf123456Content-Type:application/x-www-form-urlencodedUser-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 ارسال می شود به این سرویس در نظر گرفته شده است.
عامل کاربر برای همه درخواست‌های Action Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions) است.
اگر همه بررسی‌ها تایید شوند، سرویس می‌تواند به مرحله بعدی ادامه دهد.
مرحله 2: عمل را پردازش کنید
این سرویس باید عملکرد را همانطور که در پارامترهای URL و همچنین اطلاعات اضافی جمع آوری شده از کاربر مشخص شده است پردازش کند.
اطلاعات اضافی از کاربر در بدنه درخواست وجود دارد و با استفاده از رمزگذاری x-www-form-urleccod کدگذاری می شود. اطلاعات در ویژگی هایی تنظیم می شوند که نام آنها با ویژگی های Action مطابقت دارد. به عنوان مثال، ConfirmAction دارای ویژگی confirmed است.
مرحله 3: یک کد پاسخ را برگردانید
هنگامی که سرویس با موفقیت پردازش و ضبط کرد، باید کد پاسخ 200 (OK) را برگرداند. کدهای پاسخ زیر را می توان در موقعیت های خطا استفاده کرد:
کد پاسخ
درمان
400 (درخواست بد)
گوگل این اقدام را شکست خواهد داد.
401 (غیر مجاز)
گوگل این اقدام را شکست خواهد داد.
404 (یافت نشد)
گوگل این اقدام را شکست خواهد داد.
408 (مهلت زمانی درخواست)
Google بعداً دوباره امتحان خواهد کرد.
در صورت خرابی دائمی، گوگل به کاربر می‌گوید که عملکرد ناموفق بوده است و کاربر باید دستورالعمل‌های جایگزین داخل ایمیل را دنبال کند.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Handle Action Requests\n\nAs described in [Declaring Actions](/workspace/gmail/markup/actions/declaring-actions), when a user interacts with an In-App Action, Google sends an HTTP request to a URL declared in the action.\n\nThe following example adds a `ConfirmAction` button to an email about an expense report: \n\n### JSON-LD\n\n \u003cscript type=\"application/ld+json\"\u003e\n {\n \"@context\": \"http://schema.org\",\n \"@type\": \"EmailMessage\",\n \"potentialAction\": {\n \"@type\": \"ConfirmAction\",\n \"name\": \"Approve Expense\",\n \"handler\": {\n \"@type\": \"HttpActionHandler\",\n \"url\": \"https://myexpenses.com/approve?expenseId=abc123\"\n }\n },\n \"description\": \"Approval request for John's $10.13 expense for office supplies\"\n }\n \u003c/script\u003e\n\n### Microdata\n\n \u003cdiv itemscope itemtype=\"http://schema.org/EmailMessage\"\u003e\n \u003cdiv itemprop=\"potentialAction\" itemscope itemtype=\"http://schema.org/ConfirmAction\"\u003e\n \u003cmeta itemprop=\"name\" content=\"Approve Expense\"/\u003e\n \u003cdiv itemprop=\"handler\" itemscope itemtype=\"http://schema.org/HttpActionHandler\"\u003e\n \u003clink itemprop=\"url\" href=\"https://myexpenses.com/approve?expenseId=abc123\"/\u003e\n \u003c/div\u003e\n \u003c/div\u003e\n \u003cmeta itemprop=\"description\" content=\"Approval request for John's $10.13 expense for office supplies\"/\u003e\n \u003c/div\u003e\n\nWhen the user clicks on the button, an HTTP request will be issued from Google to your service, recording the confirmation. Your service receives the following HTTP request from Google: \n\n POST /approve?expenseId=abc123 HTTP/1.1\n Host: your-domain.com\n Authorization: Bearer AbCdEf123456\n Content-Type: application/x-www-form-urlencoded\n User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)\n\n confirmed=Approved\n\nThe rest of this page describes what the service at `https://your-domain.com/approve?expenseId=abc123` needs to do to handle the action properly. This includes:\n\n- Verifying the request\n- Processing the payload\n- Returning a response code\n\nStep 1: Verify the Request\n--------------------------\n\nThe service at `https://your-domain.com/approve?expenseId=abc123` is encouraged to check:\n\n- [Limited Use Access Token](/workspace/gmail/markup/actions/limited-use-access-tokens) - To protect against replay attacks.\n- [User Agent](http://en.wikipedia.org/wiki/User_agent) - To make sure the request comes from Google.\n- [Bearer Token](/workspace/gmail/markup/actions/verifying-bearer-tokens) - To guarantee the request coming from Google is intended to the service.\n\nThe User Agent for all Action requests is `Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)`.\n\nIf all checks pass, the service can proceed to the next step.\n\nStep 2: Process the Action\n--------------------------\n\nThe service should process the action as specified in the URL parameters as well as additional information collected from the user.\n\nAdditional information from the user resides in the request's body, and is encoded using the [x-www-form-urlecoded](https://en.wikipedia.org/wiki/Percent-encoding#The_application.2Fx-www-form-urlencoded_type) encoding. The information is set in properties whose names correspond with the properties of Action. For example, [ConfirmAction](/workspace/gmail/markup/reference/types/ConfirmAction) has the property `confirmed`.\n\nStep 3: Return a Response Code\n------------------------------\n\nOnce the service processed and recorded the action successfully, it should return a response code `200 (OK)`. The following response codes can be used in error situations:\n\n| Response Code | Treatment |\n|-----------------------|--------------------------------|\n| 400 (Bad Request) | Google will fail the action. |\n| 401 (Unauthorized) | Google will fail the action. |\n| 404 (Not Found) | Google will fail the action. |\n| 408 (Request Timeout) | Google will retry again later. |\n\nIn case of permanent failure, Google will tell the user that action has failed and that the user should follow alternative instructions inside the email.\n\nFurther Reading\n---------------\n\n- [Securing Actions](/workspace/gmail/markup/actions/securing-actions)\n\n| **Note:** Some of the schemas used by Google are still going through the standardization process of [schema.org](http://schema.org), and therefore, may change in the future. [Learn More](/workspace/gmail/markup/reference/schema-org-proposals)."]]
