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 (خطأ طلب غير صالح). يجب إعادة محاولة إرسال الطلب بعد استرداد أحدث إصدار من المستند. عادةً ما يظلّ معرّف المراجعة صالحًا للاستخدام كمراجعة مستهدَفة لعدة دقائق بعد قراءته، ولكن قد تكون هذه الفترة أقصر بالنسبة إلى المستندات التي يتم تعديلها بشكل متكرّر.