Method: documents.batchUpdate

يتم تطبيق تعديل واحد أو أكثر على المستند.

يتم التحقّق من صحة كل request قبل تطبيقها. وإذا كان أي طلب غير صالح، سيتعذّر تنفيذ الطلب بأكمله ولن يتم تطبيق أي إجراء.

تتضمّن بعض الطلبات "replies" لتزويدك ببعض المعلومات عن كيفية تطبيقها. لا تتطلّب الطلبات الأخرى إرجاع المعلومات. فكل منها ينتج ردًا فارغًا. يتطابق ترتيب الردود مع ترتيب الطلبات.

على سبيل المثال، لنفترض أنك استدعيت نسختَي التحديث بأربعة تحديثات، والثالث فقط هو الذي يعرض المعلومات. سيكون للاستجابة ردان فارغان، والرد على الطلب الثالث، ورد آخر فارغ، بهذا الترتيب.

ونظرًا لاحتمال قيام مستخدمين آخرين بتعديل المستند، فقد لا يعكس المستند التغييرات التي أجريتها بالضبط: فقد يتم تغيير التغييرات فيما يتعلق بتغييرات المتعاون. إذا لم يكن هناك متعاونون، يجب أن يعكس المستند التغييرات التي أجريتها. في أي حالة، يمكن ضمان تطبيق التعديلات في طلبك معًا على نحو ذري.

طلب HTTP

POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

مَعلمات المسار

المعلمات
documentId

string

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

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
الحقول
requests[]

object (Request)

قائمة بالتعديلات التي يجب تطبيقها على المستند
writeControl

object (WriteControl)

توفِّر هذه الميزة إمكانية التحكُّم في كيفية تنفيذ طلبات الكتابة.

نص الاستجابة

رسالة رد من طلب documents.batchUpdate.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
الحقول
documentId

string

رقم تعريف المستند الذي تم تطبيق التعديلات عليه.
replies[]

object (Response)

الرد على التعديلات. يؤدي هذا إلى الربط بين شخصين مع التعديلات، على الرغم من أن الردود على بعض الطلبات قد تكون فارغة.
writeControl

object (WriteControl)

عنصر تحكّم الكتابة المعدَّل بعد تطبيق الطلب

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

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

  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file

لمزيد من المعلومات، يُرجى الاطّلاع على دليل التفويض.

WriteControl

توفِّر هذه الميزة إمكانية التحكُّم في كيفية تنفيذ طلبات الكتابة.

تمثيل JSON 
{

  // Union field control can be only one of the following:
  "requiredRevisionId": string,
  "targetRevisionId": string
  // End of list of possible types for union field control.
}
الحقول
حقل الاتحاد control. تحديد مراجعة المستند للكتابة إليها وكيف يجب أن يتصرف الطلب إذا لم تكن هذه المراجعة هي المراجعة الحالية للمستند. في حال عدم تحديد أي من الحقلَين، يتم تطبيق التعديلات على أحدث نسخة. يمكن أن يكون control واحدًا فقط مما يلي:
requiredRevisionId

string

تمثّل هذه السمة revision ID الاختياري للمستند الذي يتم تطبيق طلب الكتابة عليه. إذا لم تكن هذه هي النسخة الأخيرة من المستند، لن تتم معالجة الطلب ويعرض رسالة الخطأ 400 الخاصة بالطلب غير صالح.

عند إرجاع معرّف النسخة السابقة المطلوب في الرد، فإنه يشير إلى معرف النسخة السابقة للمستند بعد تطبيق الطلب.
targetRevisionId

string

الهدف الاختياري revision ID للمستند الذي يتم تطبيق طلب الكتابة عليه.

إذا حدثت تغييرات في المتعاون بعد قراءة المستند باستخدام واجهة برمجة التطبيقات، يتم تطبيق التغييرات الناتجة عن طلب الكتابة هذا على تغييرات المتعاون. ينتج عن ذلك مراجعة جديدة للمستند تتضمن كلاً من تغييرات المتعاون والتغييرات في الطلب، مع حل خادم "المستندات" التغييرات المتضاربة. وعند استخدام معرّف المراجعة المستهدف، يمكن اعتبار عميل واجهة برمجة التطبيقات متعاونًا آخر في المستند.

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