الطلبات والردود

يتناول هذا الدليل طرق الطلب والاستجابة الأساسية التي تشكل واجهة برمجة التطبيقات لمحرّر مستندات Google وكيف يمكنك تحديث مستند على دفعات.

ويمكنك استدعاء Google Docs API باستخدام طلب HTTP أو باستخدام طريقة استدعاء في مكتبة عملاء خاصة بلغة محددة. وهذان العنصران متكافئان على نطاق واسع.

تعرض واجهة برمجة التطبيقات لمستندات Google استجابة HTTP، تتضمن النتيجة بشكل عام باستدعاء الطلب. عند استخدام مكتبة برامج لتقديم الطلبات، يتم إرجاع الردود بطريقة خاصة بلغة معينة.

طرق الطلب

تتيح واجهة برمجة التطبيقات لتطبيق "مستندات Google" استخدام الطرق التالية:

  • documents.create: إنشاء مستند "مستندات Google" فارغ.
  • documents.get: إرجاع المثيل الكامل للوثيقة المحددة. يمكنك تحليل ملف JSON الذي تم عرضه. لاستخراج محتوى المستند وتنسيقه والميزات الأخرى
  • documents.batchUpdate: أرسِل قائمة بطلبات التعديل لتطبيقها على المستند بشكلٍ موحّد، ثم أظهِر قائمة بالنتائج.

تتطلّب الطريقتان documents.get وdocuments.batchUpdate السمة documentId. كمعلمة لتحديد المستند المستهدف. الطريقة documents.create مثيل للمستند الذي تم إنشاؤه، والذي يمكنك من خلاله قراءة documentId لمزيد من المعلومات حول documentId، راجع مستند المعرّف

التحديثات المجمّعة

documents.batchUpdate قائمة request عنصرًا، كل عنصر ويحدد طلبًا واحدًا لتنفيذه. على سبيل المثال، قم بتنسيق فقرة ثم لإضافة صورة مضمّنة. يتم التحقق من صحة كل طلب قبل تطبيقه تتم معالجة الطلبات وفقًا للترتيب الذي تظهر به في الطلب المجمّع.

يتم تطبيق جميع الطلبات في التحديث المجمّع بشكل كامل. وهذا يعني أنّه إذا لم يكن أي طلب صالحًا، لن يتم إكمال عملية التحديث بالكامل ولن يتم تطبيق أي من التغييرات (التي قد تكون مرتبطة).

تزوِّد بعض طُرق documents.batchUpdate ردودًا بمعلومات حول. الطلبات المطبَّقة. تعرض هذه الطرق ردًا النص الأساسي الذي يحتوي على قائمة response الأخرى. ولا تحتاج الطلبات الأخرى إلى عرض معلومات وعرض طلب رد. تشغل الكائنات الموجودة في قائمة الاستجابة نفس ترتيب الفهرس الطلب المقابل.

يبدو النمط الشائع لإنشاء الطلبات المجمّعة كما يلي:

requests = []
requests.append(first request)
requests.append(second request)
...

body = ... & requests & ...

...batchUpdate(body)

راجِع أفضل ممارسات الطلبات المجمّعة لمعرفة التفاصيل الكاملة عن كيفية تجميع طلبات البيانات من واجهة برمجة التطبيقات لـ "مستندات Google" documents.batchUpdate وثائق مرجعية لأنواع الطلبات والردود.

عمليات التحديث المجمع

هناك أنواع مختلفة من طلبات التحديث المجمّع. في ما يلي تفاصيل أنواع الطلبات، التي تم تجميعها في فئات مختلفة.

الكائن إضافة أو إدراج تحديث / استبدال حذف
النص InsertTextRequest ReplaceAllTextRequest
الأنماط CreateParagraphBulletsRequest UpdateTextStyleRequest
UpdateParagraphStyleRequest
UpdateTableCellStyleRequest
UpdateTableRowStyleRequest
UpdateDocumentStyleRequest
UpdateSectionStyleRequest
DeleteParagraphBulletsRequest
النطاقات المُعنونة CreateNamedRangeRequest ReplaceNamedRangeContentRequest DeleteNamedRangeRequest
DeleteContentRangeRequest
الصور InsertInlineImageRequest ReplaceImageRequest
الجداول InsertTableRequest
InsertTableRowRequest
InsertTableColumnRequest
UpdateTableColumnPropertiesRequest
MergeTableCellsRequest
UnmergeTableCellsRequest
PinTableHeaderRowsRequest
DeleteTableRowRequest
DeleteTableColumnRequest
كائنات الصفحات (بما في ذلك الرؤوس والتذييلات) InsertPageBreakRequest
CreateHeaderRequest
CreateFooterRequest
CreateFootnoteRequest
InsertSectionBreakRequest
DeletePositionedObjectRequest
DeleteHeaderRequest
DeleteFooterRequest