Package google.firestore.admin.v1beta1

الفهرس

مشرف في متجر Firestore

واجهة برمجة تطبيقات المشرف في Cloud Firestore

توفر واجهة برمجة التطبيقات هذه العديد من الخدمات الإدارية في Cloud Firestore.

المفاهيم

يتم استخدام المشروع وقاعدة البيانات ومساحة الاسم والمجموعة والمستند كما هو موضح في واجهة برمجة تطبيقات Google Cloud Firestore.

العملية: تمثل العملية العمل الذي يتم تنفيذه في الخلفية.

الخدمات

الفهرس

تدير خدمة الفهرسة فهارس Cloud Firestore.

يتم إنشاء الفهرس بشكل غير متزامن. يتم إنشاء مورد عملية لكل عملية غير متزامنة. قد يتم الاستعلام عن حالة العملية (بما في ذلك أي أخطاء تمت مواجهتها) عبر مورد العملية.

البيانات الوصفية

توفّر هذه السياسة بيانات وصفية ومعلومات إحصائية حول البيانات في Cloud Firestore. البيانات المقدَّمة كجزء من واجهة برمجة التطبيقات هذه قد تكون قديمة.

العملية

توفر مجموعة العمليات سجلاً بالإجراءات التي تم تنفيذها للمشروع المحدد (بما في ذلك أي عمليات قيد التقدم). لا يتم إنشاء العمليات مباشرةً ولكن من خلال الطلبات على مجموعات أو موارد أخرى.

قد يتم إلغاء عملية لم يتم تنفيذها بعد. طلب الإلغاء غير متزامن وقد يستمر تنفيذ العملية لبعض الوقت بعد إجراء طلب الإلغاء.

قد يتم حذف "عملية" تم تنفيذها لكي لا يتم إدراجها كجزء من مجموعة "العملية".

يتم إنشاء العمليات من خلال الخدمة FirestoreAdmin، ولكن يتم الوصول إليها عبر خدمة google.longrunning.Operations.

إنشاء فهرس

rpc CreateIndex(CreateIndexRequest) returns (Operation)

ينشئ الفهرس المحدد. الحالة الأولية للفهرس الذي تم إنشاؤه حديثًا هي CREATING. عند إكمال عملية إرجاع google.longrunning.Operation، ستكون الولاية هي READY. إذا كان الفهرس متوفّرًا حاليًا، سيعرض الاستدعاء حالة ALREADY_EXISTS.

أثناء الإنشاء، قد تؤدي العملية إلى حدوث خطأ، وفي هذه الحالة سيتم نقل الفهرس إلى حالة ERROR. يمكن استرداد العملية عن طريق إصلاح البيانات التي تسبّبت في حدوث الخطأ، وإزالة الفهرس باستخدام delete، ثم إعادة إنشاء الفهرس باستخدام create.

لا يمكن إنشاء فهارس تتضمّن حقلاً واحدًا.

نطاقات الأذونات

يتطلب هذا الإعداد أحد نطاقات OAuth التالية:

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

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.
حذف الفهرس

rpc DeleteIndex(DeleteIndexRequest) returns (Empty)

لحذف فهرس.

نطاقات الأذونات

يتطلب هذا الإعداد أحد نطاقات OAuth التالية:

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

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.
تصدير المستندات

rpc ExportDocuments(ExportDocumentsRequest) returns (Operation)

تصدِّر نسخة من كل المستندات أو مجموعة فرعية منها من Google Cloud Firestore إلى نظام تخزين آخر، مثل Google Cloud Storage. قد لا تظهر التعديلات الأخيرة التي تم إجراؤها على المستندات في عملية التصدير. يتم التصدير في الخلفية ويمكن مراقبة مستوى تقدُّمه وإدارته من خلال مورد "العملية" الذي يتم إنشاؤه. لا يمكن استخدام ناتج عملية التصدير إلا بعد اكتمال العملية المرتبطة. في حال إلغاء عملية التصدير قبل اكتمالها، قد يؤدي ذلك إلى ترك بيانات جزئية في Google Cloud Storage.

نطاقات الأذونات

يتطلب هذا الإعداد أحد نطاقات OAuth التالية:

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

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.
مؤشر GetIndex

rpc GetIndex(GetIndexRequest) returns (Index)

الحصول على فهرس.

نطاقات الأذونات

يتطلب هذا الإعداد أحد نطاقات OAuth التالية:

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

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.
الاستيراد

rpc ImportDocuments(ImportDocumentsRequest) returns (Operation)

لاستيراد المستندات إلى Google Cloud Firestore. يتم استبدال المستندات الحالية التي تحمل الاسم نفسه. يحدث الاستيراد في الخلفية ويمكن مراقبة مستوى تقدُّمه وإدارته من خلال مورد "العملية" الذي يتم إنشاؤه. في حال إلغاء عملية الاستيراد، من المحتمل أن تكون مجموعة فرعية من البيانات قد تم استيرادها من قبل إلى Cloud Firestore.

نطاقات الأذونات

يتطلب هذا الإعداد أحد نطاقات OAuth التالية:

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

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.
فهارس القوائم

rpc ListIndexes(ListIndexesRequest) returns (ListIndexesResponse)

يتم سرد الفهارس التي تطابق الفلاتر المحددة.

نطاقات الأذونات

يتطلب هذا الإعداد أحد نطاقات OAuth التالية:

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

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة حول المصادقة.

إنشاء طلب فهرس

طلب الحصول على FirestoreAdmin.CreateIndex

الحقول
parent

string

اسم قاعدة البيانات التي سيتم تطبيق هذا الفهرس عليها. مثلاً: projects/{project_id}/databases/{database_id}
index

Index

الفهرس المطلوب إنشاؤه. إنّ حقلَي الاسم والحالة هما الناتجان فقط وسيتم تجاهلهما. لا يمكن إنشاء فهارس حقول فردية معيَّنة أو حذفها.

طلب حذف الفهرس

طلب الحصول على FirestoreAdmin.DeleteIndex

الحقول
name

string

اسم الفهرس. مثلاً: projects/{project_id}/databases/{database_id}/indexes/{index_id}

ExportDocumentsMetadata

البيانات الوصفية لعمليات ExportDocuments

الحقول
start_time

Timestamp

الوقت الذي بدأ فيه العمل على العملية
end_time

Timestamp

الوقت الذي انتهت فيه العملية، سواء بنجاح أو غير ذلك. لا يتم تحديده إذا كانت العملية لا تزال نشطة.
operation_state

OperationState

حالة عملية التصدير.
progress_documents

Progress

تقدير لعدد المستندات التي تمت معالجتها.
progress_bytes

Progress

تقدير لعدد وحدات البايت التي تمت معالجتها.
collection_ids[]

string

أرقام تعريف المجموعات التي يتم تصديرها
output_uri_prefix

string

المكان الذي يتم تصدير العناصر إليه

طلب تصدير المستندات

طلب الحصول على FirestoreAdmin.ExportDocuments

الحقول
name

string

قاعدة البيانات المراد تصديرها. يجب أن يكون بالتنسيق: projects/{project_id}/databases/{database_id}.
collection_ids[]

string

معرّفات المجموعات المطلوب تصديرها. ويشير "غير محدّدة" إلى كل المجموعات.
output_uri_prefix

string

معرّف الموارد المنتظم (URI) الناتج. لا يتوافق هذا الإعداد حاليًا إلا مع معرّفات الموارد المنتظمة (URI) لخدمة Google Cloud Storage على النحو التالي: gs://BUCKET_NAME[/NAMESPACE_PATH]، حيث يكون BUCKET_NAME هو اسم حزمة Google Cloud Storage وNAMESPACE_PATH مسار اختياري لمساحة الاسم في Google Cloud Storage. عند اختيار اسم، احرص على مراعاة إرشادات التسمية في Google Cloud Storage: https://cloud.google.com/storage/docs/naming. إذا كان معرِّف الموارد المنتظم (URI) عبارة عن مجموعة بيانات (بدون مسار مساحة اسم)، سيتم إنشاء بادئة استنادًا إلى وقت البدء.

ExportDocumentsResponse

تم عرضه في حقل الاستجابة google.longrunning.Operation.

الحقول
output_uri_prefix

string

موقع ملفات الإخراج: ويمكن استخدام ذلك لبدء عملية استيراد إلى Cloud Firestore (هذا المشروع أو مشروع آخر) بعد اكتمال العملية بنجاح.

طلب GetIndexRequest

طلب الحصول على FirestoreAdmin.GetIndex

الحقول
name

string

تمثّل هذه السمة اسم الفهرس. مثلاً: projects/{project_id}/databases/{database_id}/indexes/{index_id}

ImportDocumentsMetadata

البيانات الوصفية لعمليات الاستيراد

الحقول
start_time

Timestamp

الوقت الذي بدأ فيه العمل على العملية
end_time

Timestamp

وقت انتهاء العملية، سواء بنجاح أو غير ذلك. لا يتم تحديده إذا كانت العملية لا تزال نشطة.
operation_state

OperationState

حالة عملية الاستيراد.
progress_documents

Progress

تقدير لعدد المستندات التي تمت معالجتها.
progress_bytes

Progress

تقدير لعدد وحدات البايت التي تمت معالجتها.
collection_ids[]

string

معرّفات المجموعات التي يتم استيرادها.
input_uri_prefix

string

موقع المستندات التي يتم استيرادها.

طلب استيراد المستندات

طلب الحصول على FirestoreAdmin.ImportDocuments

الحقول
name

string

قاعدة بيانات للاستيراد إليها. يجب أن يكون بالتنسيق: projects/{project_id}/databases/{database_id}.
collection_ids[]

string

معرّفات المجموعات المطلوب استيرادها. تعني عبارة "غير محدّدة" كل المجموعات المضمّنة في عملية الاستيراد.
input_uri_prefix

string

موقع الملفات التي تم تصديرها يجب أن يتطابق هذا الحقل مع معلَمة Export_uri_prefix الخاصة بـ ExportDocumentsResponse من عملية التصدير التي اكتملت بنجاح. يمكنك الاطّلاع على: google.firestore.admin.v1beta1.ExportDocumentsResponse.output_uri_prefix.

الفهرس

تعريف فهرس.

الحقول
name

string

اسم مورد الفهرس. النتائج فقط.
collection_id

string

معرّف المجموعة الذي ينطبق عليه هذا الفهرس. مطلوب.
fields[]

IndexField

الحقول المطلوب فهرستها.
state

State

حالة الفهرس. النتائج فقط.

الولاية

حالة الفهرس. أثناء إنشاء الفهرس، سيكون الفهرس في حالة CREATING. إذا تم إنشاء الفهرس بنجاح، سينتقل إلى حالة READY. وإذا تعذّر إنشاء الفهرس، سيتم نقله إلى حالة ERROR.

تعدادات
STATE_UNSPECIFIED لم يتم تحديد الولاية.
CREATING يتم إنشاء الفهرس. هناك عملية نشطة طويلة الأمد للفهرس. يتم تعديل الفهرس عند كتابة مستند. قد تتوفّر بعض بيانات الفهرس.
READY الفهرس جاهز للاستخدام. يتم تعديل الفهرس عند كتابة مستند. تتم تعبئة الفهرس بالكامل من جميع المستندات المخزنة التي ينطبق عليها.
ERROR كان يتم إنشاء الفهرس، ولكن حدث خطأ ما. ليس هناك عملية نشطة طويلة الأمد للفهرس، وتعذّر إتمام آخر عملية طويلة الأمد. لا يتم تعديل الفهرس عند كتابة مستند. قد تتوفّر بعض بيانات الفهرس.

حقل الفهرس

حقل في فهرس

الحقول
field_path

string

مسار الحقل. يجب أن يتطابق مع مواصفات مسار الحقل الموضّحة في [google.firestore.v1beta1.Document.fields][الحقول]. ويمكن استخدام مسار الحقل الخاص __name__ بمفرده أو في نهاية مسار. لا يمكن استخدام __type__ إلا في نهاية المسار.
mode

Mode

وضع الحقل.

الوضع

يحدّد الوضع كيفية فهرسة الحقل.

تعدادات
MODE_UNSPECIFIED الوضع غير محدّد.
ASCENDING تتم فهرسة قيم الحقل لدعم التسلسل التصاعدي وأيضًا الاستعلام باستخدام < و> و<= و>= و =.
DESCENDING تتم فهرسة قيم الحقل لدعم التسلسل التنازلي وكذلك الاستعلام باستخدام < و> و<= و>= و =.
ARRAY_CONTAINS تتم فهرسة قيم مصفوفة الحقل من أجل إتاحة العضوية باستخدام طلبات بحث ARRAY_CONTAINS.

البيانات الوصفية الخاصة بعملية الفهرسة

البيانات الوصفية لعمليات الفهرس تعمل هذه البيانات الوصفية على تعبئة حقل البيانات الوصفية google.longrunning.Operation.

الحقول
start_time

Timestamp

الوقت الذي بدأ فيه العمل على العملية
end_time

Timestamp

الوقت الذي انتهت فيه العملية، سواء بنجاح أو غير ذلك. لا يتم تحديده إذا كانت العملية لا تزال نشطة.
index

string

يشير إلى مورد الفهرس الذي يتم تطبيق هذه العملية عليه. مثلاً: projects/{project_id}/databases/{database_id}/indexes/{index_id}
operation_type

OperationType

نوع عملية الفهرس.
cancelled

bool

صحيح إذا تم إلغاء google.longrunning.Operation. إذا كانت عملية الإلغاء قيد التقدّم، تكون قيمة الإلغاء صحيحة بينما ستكون السمة google.longrunning.Operation.done خاطئة.
document_progress

Progress

مستوى تقدُّم العملية الحالية، ويتم قياسه من خلال عدد المستندات

نوع العملية

نوع عملية الفهرس.

تعدادات
OPERATION_TYPE_UNSPECIFIED غير محدَّد لا يتم الضبط مطلقًا من قِبل الخادم.
CREATING_INDEX تكون العملية هي إنشاء الفهرس. تم البدء من خلال مكالمة CreateIndex.

طلب ListIndexesRequest

طلب الحصول على FirestoreAdmin.ListIndexes

الحقول
parent

string

اسم قاعدة البيانات. مثلاً: projects/{project_id}/databases/{database_id}
filter

string
page_size

int32

حجم صفحة القائمة العادي.
page_token

string

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

استجابة ListIndexesResponse

تمثّل هذه السمة الردّ على FirestoreAdmin.ListIndexes.

الحقول
indexes[]

Index

الفهارس.
next_page_token

string

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

البيانات الوصفية للمواقع الجغرافية

لا يحتوي هذا النوع على أي حقول.

رسالة البيانات الوصفية لـ google.cloud.location.Location.metadata.

حالة العملية

الحالات المختلفة المحتملة لعملية جارية.

تعدادات
STATE_UNSPECIFIED غير محدَّد
INITIALIZING يتم إعداد الطلب للمعالجة.
PROCESSING تجري معالجة الطلب بشكل نشط.
CANCELLING يتم إلغاء الطلب بعد تفعيل المستخدم المسمى google.longrun.Operations.CancelOperation.
FINALIZING تمت معالجة الطلب وهو في مرحلة المعالجة النهائية.
SUCCESSFUL اكتمل الطلب بنجاح.
FAILED انتهت معالجة الطلب، ولكن حدث خطأ.
CANCELLED اكتمل إلغاء الطلب بعد أن يحمل المستخدم الاسم google.longrun.Operations.CancelOperation.

التقدم

يشير إلى مدى التقدم المحرز في مقياس معين.

الحقول
work_completed

int64

تقدير لمقدار العمل الذي تم إنجازه. يُرجى العِلم أنّ هذه القيمة قد تكون أكبر من work_estimated.
work_estimated

int64

تقدير لمقدار العمل الذي يجب القيام به. صفر في حال عدم توفّر تقدير العمل. قد يتغير مع تقدم العمل.