Method: documents.batchUpdate

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

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

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

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

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

طلب 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 المستهدَف للمستند الذي يتم تطبيق طلب الكتابة عليه.

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

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