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)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
الحقول
documentId

string

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

object (Response)

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

object (WriteControl)

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

object (SuggestionResponse)

الاقتراحات التي تأثّرت بكلّ تعديل ويتم ربط ذلك بالتحديثات بنسبة 1:1.
commentUpdateState

enum (CommentUpdateState)

تُستخدَم لتحديد ما إذا تم تطبيق تعديلات التعليقات في طلب الدفعة.

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

يجب توفير أحد نطاقات OAuth التالية:

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

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

WriteControl

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

تمثيل JSON 
{
  "writeMode": enum (WriteMode),

  "requiredRevisionId": string,
  "targetRevisionId": string
}
الحقول
writeMode

enum (WriteMode)

كيفية تطبيق تعديلات الطلب على المستند

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

string

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

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

string

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

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

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

WriteMode

تحدّد هذه السمة كيفية تطبيق تعديلات الطلب على المستند.

عمليات التعداد
WRITE_MODE_UNSPECIFIED لم يتم تحديد وضع الكتابة. يكون السلوك التلقائي هو EDIT.
EDIT تطبيق جميع التعديلات كتعديلات عادية
SUGGEST تطبيق جميع التعديلات كاقتراحات

SuggestionResponse

الاقتراحات التي تأثّرت بتحديث معيّن

تمثيل JSON 
{
  "createdSuggestionIds": [
    string
  ],
  "updatedSummarySuggestionIds": [
    string
  ],
  "deletedSuggestionIds": [
    string
  ],
  "acceptedSuggestionIds": [
    string
  ],
  "rejectedSuggestionIds": [
    string
  ]
}
الحقول
createdSuggestionIds[]

string

معرّفات الاقتراحات التي تم إنشاؤها أثناء التعديل
updatedSummarySuggestionIds[]

string

معرّفات الاقتراحات التي تم تعديل ملخّصاتها أثناء التعديل
deletedSuggestionIds[]

string

معرّفات الاقتراحات التي تم حذفها أثناء التحديث
acceptedSuggestionIds[]

string

معرّفات الاقتراحات التي تم قبولها أثناء التحديث
rejectedSuggestionIds[]

string

معرّفات الاقتراحات التي تم رفضها أثناء التحديث.

CommentUpdateState

حالة تعديلات التعليقات في طلب الدفعة

عمليات التعداد
COMMENT_UPDATE_STATE_UNSPECIFIED لم يتم تحديد حالة تعديلات التعليقات.
NO_UPDATES_REQUESTED لم يتم طلب أي تعديلات على التعليقات في طلب الدفعة.
ALL_SAVED تم تطبيق جميع التعديلات المطلوبة على التعليقات في طلب الدُفعة.
ALL_FAILED_UNKNOWN_REASON تعذّر إجراء جميع التعديلات المطلوبة على التعليقات.