Package google.longrunning

الفهرس

العمليات

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

عندما تستغرق إحدى طرق واجهة برمجة التطبيقات وقتًا طويلاً لإكمالها، يمكن تصميمها لعرض Operation للعميل، ويمكن للعميل استخدام هذه الواجهة لتلقّي الرد الفعلي بشكل غير متزامن من خلال التحقّق من مورد العملية، أو تمرير مورد العملية إلى واجهة برمجة تطبيقات أخرى (مثل Pub/Sub API) لتلقّي الرد. يجب أن تنفّذ أي خدمة واجهة برمجة تطبيقات تعرض عمليات طويلة الأمد واجهة 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
أذونات "إدارة الهوية وإمكانية الوصول"

يتطلّب هذا الإجراء إذن إدارة الهوية وإمكانية الوصول (IAM) التالي على مورد name:

  • routeoptimization.operations.get

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات إدارة الهوية وإمكانية الوصول.
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

الرمز المميز لصفحة القائمة العادية
return_partial_success

bool

عند ضبطها على true، يتم عرض العمليات التي يمكن الوصول إليها بشكل عادي، ويتم عرض العمليات التي لا يمكن الوصول إليها في الحقل [ListOperationsResponse.unreachable].

يمكن أن تكون القيمة true فقط عند القراءة من مجموعات متعددة، مثلاً عندما تكون قيمة parent هي "projects/example/locations/-".

لا يكون هذا الحقل متاحًا تلقائيًا، وسيؤدي إلى ظهور الخطأ UNIMPLEMENTED في حال ضبطه ما لم يتم توثيقه بشكل صريح في مستندات الخدمة أو المنتج.

ListOperationsResponse

رسالة الردّ على Operations.ListOperations

الحقول
operations[]

Operation

قائمة بالعمليات التي تتطابق مع الفلتر المحدّد في الطلب
next_page_token

string

الرمز المميز العادي للصفحة التالية في قائمة.
unreachable[]

string

قائمة بدون ترتيب المراجع التي لا يمكن الوصول إليها يتم ملء هذا الحقل عندما يضبط الطلب ListOperationsRequest.return_partial_success ويقرأ في جميع المجموعات، مثلاً عند محاولة إدراج جميع الموارد في جميع المواقع الجغرافية المتوافقة.

العملية

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

الحقول
name

string

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

Any

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

bool

إذا كانت القيمة false، هذا يعني أنّ العملية ما زالت قيد التنفيذ. أما إذا كانت true، فهذا يعني أنّ العملية اكتملت، ويمكن عندها الوصول إلى error أو response.
حقل الدمج result تمثّل نتيجة العملية، والتي يمكن أن تكون إما error أو response صالحة. إذا كان false ‏== done، هذا يعني أنّه لم يتم ضبط أي من error أو response. إذا كان true ‏== done، هذا يعني أنّه يمكن ضبط إما 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 أيضًا، سيتم استخدام الموعد الأقصر.