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)

ردّ التحديثات ويتم ربط هذا الحقل بالتحديثات بنسبة 1:1، على الرغم من أنّ الردود على بعض الطلبات قد تكون فارغة.
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 Bad Request.

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

string

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

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

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