Package google.longrunning

فهرست

• Operations (رابط)
• CancelOperationRequest (پیام)
• DeleteOperationRequest (پیام)
• GetOperationRequest (پیام)
• ListOperationsRequest (پیام)
• ListOperationsResponse (پیام)
• Operation (پیام)
• WaitOperationRequest (پیام)

عملیات

عملیات طولانی مدت را با یک سرویس API مدیریت می‌کند.

وقتی یک متد API معمولاً زمان زیادی برای تکمیل شدن نیاز دارد، می‌توان آن را طوری طراحی کرد که Operation به کلاینت برگرداند و کلاینت می‌تواند از این رابط برای دریافت پاسخ واقعی به صورت غیرهمزمان با نمونه‌برداری از منبع عملیات استفاده کند، یا منبع عملیات را به API دیگری (مانند Pub/Sub API) برای دریافت پاسخ ارسال کند. هر سرویس API که عملیات طولانی مدت را برمی‌گرداند، باید رابط Operations را پیاده‌سازی کند تا توسعه‌دهندگان بتوانند یک تجربه کلاینت ثابت داشته باشند.

لغو عملیات

rpc CancelOperation( CancelOperationRequest ) returns ( Empty ) لغو ناهمزمان را در یک عملیات طولانی مدت شروع می‌کند. سرور تمام تلاش خود را برای لغو عملیات انجام می‌دهد، اما موفقیت تضمین شده نیست. اگر سرور از این روش پشتیبانی نکند، google.rpc.Code.UNIMPLEMENTED را برمی‌گرداند. کلاینت‌ها می‌توانند از Operations.GetOperation یا روش‌های دیگر برای بررسی اینکه آیا لغو موفقیت‌آمیز بوده یا اینکه آیا عملیات با وجود لغو کامل شده است، استفاده کنند. در صورت لغو موفقیت‌آمیز، عملیات حذف نمی‌شود؛ در عوض، به عملیاتی با مقدار Operation.error با google.rpc.Status.code برابر با 1 ، معادل Code.CANCELLED ، تبدیل می‌شود. دامنه‌های مجوز به محدوده OAuth زیر نیاز دارد: https://www.googleapis.com/auth/cloud-platform

عملیات حذف
rpc DeleteOperation( DeleteOperationRequest ) returns ( Empty ) یک عملیات طولانی مدت را حذف می‌کند. این متد نشان می‌دهد که کلاینت دیگر علاقه‌ای به نتیجه عملیات ندارد. این متد عملیات را لغو نمی‌کند. اگر سرور از این متد پشتیبانی نکند، google.rpc.Code.UNIMPLEMENTED برمی‌گرداند. دامنه‌های مجوز به محدوده OAuth زیر نیاز دارد: https://www.googleapis.com/auth/cloud-platform

عملیات دریافت

rpc GetOperation( GetOperationRequest ) returns ( Operation ) آخرین وضعیت یک عملیات طولانی مدت را دریافت می‌کند. کلاینت‌ها می‌توانند از این متد برای نظرسنجی از نتیجه عملیات در فواصل زمانی توصیه شده توسط سرویس API استفاده کنند. دامنه‌های مجوز به محدوده OAuth زیر نیاز دارد: https://www.googleapis.com/auth/cloud-platform مجوزهای IAM به مجوز IAM زیر در منبع name نیاز دارد: routeoptimization.operations.get برای اطلاعات بیشتر، به مستندات IAM مراجعه کنید.

عملیات لیست
rpc ListOperations( ListOperationsRequest ) returns ( ListOperationsResponse ) عملیاتی را که با فیلتر مشخص شده در درخواست مطابقت دارند، فهرست می‌کند. اگر سرور از این روش پشتیبانی نکند، UNIMPLEMENTED برمی‌گرداند. دامنه‌های مجوز به محدوده OAuth زیر نیاز دارد: https://www.googleapis.com/auth/cloud-platform

عملیات صبر کنید

rpc WaitOperation( WaitOperationRequest ) returns ( Operation ) منتظر می‌ماند تا عملیات طولانی‌مدت مشخص‌شده انجام شود یا حداکثر به یک مهلت زمانی مشخص برسد و آخرین وضعیت را برمی‌گرداند. اگر عملیات قبلاً انجام شده باشد، آخرین وضعیت بلافاصله برگردانده می‌شود. اگر مهلت زمانی مشخص‌شده بیشتر از مهلت زمانی پیش‌فرض HTTP/RPC باشد، از مهلت زمانی HTTP/RPC استفاده می‌شود. اگر سرور از این روش پشتیبانی نکند، google.rpc.Code.UNIMPLEMENTED را برمی‌گرداند. توجه داشته باشید که این روش بر اساس بهترین تلاش است. ممکن است آخرین وضعیت را قبل از مهلت زمانی مشخص‌شده (از جمله بلافاصله) برگرداند، به این معنی که حتی یک پاسخ فوری تضمینی برای انجام عملیات نیست. دامنه‌های مجوز به محدوده OAuth زیر نیاز دارد: https://www.googleapis.com/auth/cloud-platform

لغو درخواست عملیات

پیام درخواست برای Operations.CancelOperation .

فیلدها
name	string نام منبع عملیاتی که باید لغو شود.

درخواست عملیات حذف

پیام درخواست برای Operations.DeleteOperation .

فیلدها
name	string نام منبع عملیاتی که قرار است حذف شود.

درخواست عملیات دریافت

پیام درخواست برای Operations.GetOperation .

فیلدها
name	string نام منبع عملیات.

درخواست عملیات لیست

پیام درخواست برای Operations.ListOperations .

فیلدها
name	string نام منبع والد عملیات.
filter	string فیلتر لیست استاندارد.
page_size	int32 اندازه استاندارد صفحه فهرست
page_token	string توکن استاندارد صفحه لیست.
return_partial_success	bool وقتی روی true تنظیم شود، عملیاتی که قابل دسترسی هستند به صورت عادی برگردانده می‌شوند و عملیاتی که قابل دسترسی نیستند در فیلد [ListOperationsResponse.unreachable] برگردانده می‌شوند. این فقط می‌تواند هنگام خواندن بین مجموعه‌ها true باشد، مثلاً وقتی parent روی "projects/example/locations/-" تنظیم شده باشد. این فیلد به طور پیش‌فرض پشتیبانی نمی‌شود و در صورت تنظیم، منجر به خطای UNIMPLEMENTED خواهد شد، مگر اینکه صراحتاً خلاف آن در مستندات خاص سرویس یا محصول ذکر شده باشد.

پاسخ عملیات لیست

پیام پاسخ برای Operations.ListOperations .

فیلدها
operations[]	Operation فهرستی از عملیات که با فیلتر مشخص شده در درخواست مطابقت دارند.
next_page_token	string توکن استاندارد List next-page.
unreachable[]	string لیست نامرتب. منابع غیرقابل دسترس. زمانی که درخواست، ListOperationsRequest.return_partial_success تنظیم می‌کند و در مجموعه‌ها می‌خواند، مثلاً هنگام تلاش برای فهرست کردن تمام منابع در تمام مکان‌های پشتیبانی‌شده، مقداردهی می‌شود.

عملیات

این منبع نشان دهنده یک عملیات طولانی مدت است که نتیجه یک فراخوانی API شبکه است.

فیلدها
name	string نام اختصاص داده شده توسط سرور، که فقط در همان سرویسی که در ابتدا آن را برمی‌گرداند، منحصر به فرد است. اگر از نگاشت پیش‌فرض HTTP استفاده می‌کنید، name باید نام منبعی باشد که به operations/{unique_id} ختم می‌شود.
metadata	Any فراداده‌های مختص سرویس مرتبط با عملیات. معمولاً شامل اطلاعات پیشرفت و فراداده‌های رایج مانند زمان ایجاد است. برخی از سرویس‌ها ممکن است چنین فراداده‌ای را ارائه ندهند. هر متدی که یک عملیات طولانی مدت را برمی‌گرداند، باید نوع فراداده را، در صورت وجود، مستند کند.
done	bool اگر مقدار آن false باشد، به این معنی است که عملیات هنوز در حال انجام است. اگر true ، عملیات تکمیل شده و error یا response در دسترس است.
result فیلد Union. نتیجه عملیات، که می‌تواند یک error یا یک response معتبر باشد. اگر done == false ، نه error و نه response تنظیم نمی‌شوند. اگر done == true ، دقیقاً یکی از error یا response می‌تواند تنظیم شود. برخی از سرویس‌ها ممکن است نتیجه را ارائه ندهند. result فقط می‌تواند یکی از موارد زیر باشد:
error	Status نتیجه خطای عملیات در صورت عدم موفقیت یا لغو.
response	Any پاسخ عادی و موفقیت‌آمیز عملیات. اگر متد اصلی هیچ داده‌ای مانند Delete در صورت موفقیت برنگرداند، پاسخ google.protobuf.Empty خواهد بود. اگر متد اصلی Get / Create / Update استاندارد باشد، پاسخ باید resource باشد. برای متدهای دیگر، پاسخ باید از نوع XxxResponse باشد، که در آن Xxx نام متد اصلی است. به عنوان مثال، اگر نام متد اصلی TakeSnapshot() باشد، نوع پاسخ استنباط شده TakeSnapshotResponse خواهد بود.

درخواست عملیات منتظر بمانید

پیام درخواست برای Operations.WaitOperation .

فیلدها
name	string نام منبع عملیاتی که باید منتظر آن ماند.
timeout	Duration حداکثر مدت زمان انتظار قبل از اتمام زمان. اگر خالی گذاشته شود، حداکثر زمان مجاز توسط پروتکل HTTP/RPC مربوطه خواهد بود. اگر مهلت زمینه RPC نیز مشخص شده باشد، از کوتاه‌ترین آن استفاده خواهد شد.