Method: documents.batchUpdate

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

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

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

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

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

طلب HTTP

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

يستخدم عنوان URL بنية gRPC Transcode.

معلّمات المسار

المَعلمات
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

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

التحكّم في الكتابة

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

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