Package google.longrunning

الفهرس

العمليات

يدير العمليات طويلة الأمد باستخدام خدمة واجهة برمجة التطبيقات.

عندما تستغرق طريقة واجهة برمجة التطبيقات عادةً وقتًا طويلاً حتى تكتمل، يمكن تصميمها لعرض Operation إلى العميل، ويمكن للعميل استخدام هذه الواجهة لتلقّي الاستجابة الحقيقية بشكل غير متزامن من خلال استطلاع رأي مورد العملية، أو تمرير مورد العملية إلى واجهة برمجة تطبيقات أخرى (مثل واجهة برمجة تطبيقات Pub/Sub) لتلقّي الرد. على أي خدمة من خدمات واجهة برمجة التطبيقات التي تعرض عمليات طويلة المدى تنفيذ واجهة Operations حتى يتمكّن المطوّرون من تقديم تجربة عميل متسقة.

CancelOperation

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
DeleteOperation

rpc DeleteOperation(DeleteOperationRequest) returns (Empty)

حذف عملية طويلة المدى وتشير هذه الطريقة إلى أنّ العميل لم يعُد مهتمًا بنتيجة العملية. ولا يؤدي ذلك إلى إلغاء العملية. إذا كان الخادم لا يتيح هذه الطريقة، يعرض الرمز google.rpc.Code.UNIMPLEMENTED.

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/cloud-platform
GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

يحصل على أحدث حالة من عملية طويلة المدى. ويمكن للعملاء استخدام هذه الطريقة لاستطلاع نتائج العملية على فترات زمنية كما تنصح خدمة واجهة برمجة التطبيقات.

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/cloud-platform
ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

يسرد العمليات التي تتطابق مع الفلتر المحدَّد في الطلب. إذا كان الخادم لا يتيح هذه الطريقة، يعرض الرمز UNIMPLEMENTED.

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/cloud-platform
WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation)

انتظر حتى تنتهي عملية التشغيل لفترة طويلة المحدّدة أو تصل إلى مهلة محدّدة على الأكثر، مع عرض آخر حالة. إذا سبق أن اكتملت العملية، ستظهر آخر حالة على الفور. إذا كانت المهلة المحددة أكبر من مهلة HTTP/RPC التلقائية، فسيتم استخدام مهلة HTTP/RPC. إذا كان الخادم لا يتيح هذه الطريقة، يعرض google.rpc.Code.UNIMPLEMENTED. تجدر الإشارة إلى بذل هذه الطريقة لبذل أفضل الجهود. وقد يعرض آخر حالة قبل المهلة المحدّدة (بما في ذلك على الفور)، ما يعني أنّه حتى الردّ الفوري لا يضمن تنفيذ العملية.

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/cloud-platform

CancelOperationRequest

رسالة الطلب التي تخصّ Operations.CancelOperation.

الحقول
name

string

اسم مورد العملية المراد إلغاؤه

DeleteOperationRequest

رسالة الطلب التي تخصّ Operations.DeleteOperation.

الحقول
name

string

اسم مورد العملية المراد حذفه.

GetOperationRequest

رسالة الطلب التي تخصّ Operations.GetOperation.

الحقول
name

string

اسم مورد العملية

ListOperationsRequest

رسالة الطلب التي تخصّ Operations.ListOperations.

الحقول
name

string

اسم المورد الرئيسي للعملية

filter

string

فلتر القائمة العادي.

page_size

int32

حجم صفحة القائمة القياسي.

page_token

string

الرمز المميز لصفحة القائمة القياسية.

ListOperationsResponse

رسالة الرد لـ Operations.ListOperations.

الحقول
operations[]

Operation

قائمة بالعمليات التي تطابق عامل التصفية المحدد في الطلب.

next_page_token

string

الرمز المميز العادي للقائمة التالية.

العملية

يمثل هذا المورد عملية طويلة الأمد ناتجة عن طلب بيانات من واجهة برمجة تطبيقات الشبكة.

الحقول
name

string

الاسم الذي يعيّنه الخادم، والذي يكون فريدًا فقط داخل الخدمة نفسها التي تُرجعه في الأصل. في حال استخدام عملية ربط HTTP التلقائية، يجب أن يكون name اسم مورد ينتهي بـ operations/{unique_id}.

metadata

Any

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

done

bool

إذا كانت القيمة false، يعني ذلك أنّ العملية لا تزال قيد التنفيذ. إذا true، تكتمل العملية، وسيكون error أو response متاحًا.

حقل الاتحاد result نتيجة العملية، والتي يمكن أن تكون error أو response صالحة. إذا كانت done == false، لن يتم ضبط error أو response. إذا كانت done == true، يمكن ضبط قيمة واحدة من error أو response بالضبط. قد لا تقدّم بعض الخدمات النتيجة. يمكن أن يكون الحقل "result" واحدًا فقط مما يلي:
error

Status

نتيجة الخطأ للعملية في حال الإخفاق أو الإلغاء.

response

Any

الاستجابة العادية والناجحة للعملية. إذا لم تعرض الطريقة الأصلية أي بيانات عن النجاح، مثل Delete، تكون الاستجابة google.protobuf.Empty. إذا كانت الطريقة الأصلية هي Get/Create/Update، يجب أن يكون الرد هو المورد. بالنسبة إلى الطرق الأخرى، يجب أن يكون نوع الاستجابة XxxResponse، حيث يكون Xxx هو اسم الطريقة الأصلية. على سبيل المثال، إذا كان اسم الطريقة الأصلية هو TakeSnapshot()، يكون نوع الردّ الذي تمّ استنتاجه هو TakeSnapshotResponse.

WaitOperationRequest

رسالة الطلب التي تخصّ Operations.WaitOperation.

الحقول
name

string

اسم مورد العملية المطلوب انتظاره.

timeout

Duration

تمثّل هذه السمة أقصى مدة يجب الانتظار فيها قبل انتهاء المهلة. وفي حال ترك هذا الحقل فارغًا، سيكون وقت الانتظار كحد أقصى هو الوقت الذي يسمح به بروتوكول HTTP/RPC الأساسي. إذا تم أيضًا تحديد الموعد النهائي لسياق استدعاء إجراء عن بُعد (RPC)، فسيتم استخدام الموعد النهائي الأقصر.