تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يوضّح هذا المستند كيفية تجميع طلبات البيانات من واجهة برمجة التطبيقات في دُفعات لتقليل عدد الاتصالات التي يجب أن يجريها العميل. يمكن أن يؤدي تجميع البيانات إلى تحسين كفاءة التطبيق من خلال تقليل عدد الرحلات المتكررة على الشبكة وزيادة سرعة نقل البيانات.
نظرة عامة
يؤدي كل اتصال يجريه العميل إلى قدر معيّن من الحمل الزائد.
تتيح واجهة Google Slides API التجميع لكي يتمكّن العميل من وضع عناصر طلبات متعدّدة، يحدّد كل منها نوعًا واحدًا من الطلبات المطلوب تنفيذها، في طلب مجمّع واحد. يمكن أن يؤدي طلب الدُفعات إلى تحسين الأداء من خلال الجمع بين طلبات فرعية متعددة في طلب واحد إلى الخادم، ما يؤدي إلى استرداد رد واحد.
ننصح المستخدمين دائمًا بتجميع الطلبات المتعددة معًا. في ما يلي بعض الأمثلة على الحالات التي يمكنك فيها استخدام التجميع:
لقد بدأت للتو في استخدام واجهة برمجة التطبيقات ولديك الكثير من البيانات لتحميلها.
عندما تحتاج إلى تعديل البيانات الوصفية أو الخصائص، مثل التنسيق، في عناصر متعدّدة
عليك حذف العديد من العناصر.
اعتبارات الحدود والأذونات والتبعيات
في ما يلي قائمة بعناصر أخرى يجب مراعاتها عند استخدام التعديل المجمّع:
يتم احتساب كل طلب مجمّع، بما في ذلك جميع الطلبات الفرعية، كطلب واحد من واجهة برمجة التطبيقات ضمن حد الاستخدام.
تتم المصادقة على طلب الدفع المجمّع مرة واحدة. تنطبق عملية المصادقة الفردية هذه على جميع عناصر التعديل المجمّع في الطلب.
يعالج الخادم الطلبات الفرعية بالترتيب نفسه الذي تظهر به في طلب الدفعة. يمكن أن تعتمد الطلبات الفرعية اللاحقة على الإجراءات المتخذة خلال الطلبات الفرعية السابقة. على سبيل المثال، في طلب الدفعة نفسه، يمكن للمستخدمين إدراج نص في مستند حالي ثم تنسيقه.
تفاصيل الدفعة
يتألف الطلب المجمّع من استدعاء واحد لطريقة batchUpdate مع طلبات فرعية متعددة، مثلاً لإضافة عرض تقديمي ثم تنسيقه.
ويتم التحقّق من صحة كل طلب قبل تطبيقه. يتم تطبيق جميع الطلبات الفرعية في التعديل المجمّع بشكل متزامن. وهذا يعني أنّه إذا كان أي طلب غير صالح، سيتعذّر إجراء التعديل بأكمله ولن يتم تطبيق أي من التغييرات (التي قد تكون مرتبطة).
تقدّم بعض الطلبات ردودًا تتضمّن معلومات حول الطلبات التي تم تطبيقها.
على سبيل المثال، تعرض جميع طلبات التعديل المجمّع لإضافة عناصر ردودًا حتى تتمكّن من الوصول إلى البيانات الوصفية للعنصر الذي تمت إضافته حديثًا، مثل المعرّف أو العنوان.
باستخدام هذا الأسلوب، يمكنك إنشاء مستند Google بالكامل باستخدام طلب واحد لتعديل مجموعة من البيانات في واجهة برمجة التطبيقات يتضمّن طلبات فرعية متعددة.
تنسيق طلب مجمّع
الطلب هو طلب JSON واحد يحتوي على طلبات فرعية متعددة ومتداخلة مع سمة واحدة مطلوبة هي requests. يتم إنشاء الطلبات في مصفوفة من الطلبات الفردية. يستخدم كل طلب JSON لتمثيل عنصر الطلب واحتواء خصائصه.
تنسيق الردّ المجمّع
يكون تنسيق الرد لطلب مجمّع مشابهًا لتنسيق الطلب. تحتوي استجابة الخادم على ردّ كامل على عنصر الاستجابة الفردي.
اسم السمة الرئيسية لعنصر JSON هو replies. يتم عرض الردود في مصفوفة، ويشغل كل رد على أحد الطلبات ترتيب الفهرس نفسه الذي يشغله الطلب المقابل. لا تتضمّن بعض الطلبات ردودًا، ويكون الردّ في فهرس المصفوفة هذا فارغًا.
مثال
يوضّح نموذج الرمز التالي كيفية استخدام التجميع مع Slides API.
تعرض استجابة الدفعة النموذجية هذه معلومات حول كيفية تطبيق كل طلب فرعي ضمن طلب الدفعة. يُرجى العِلم أنّ الطريقة
InsertTextRequest
لا تتضمّن ردًا، لذا تتألف قيمة الفهرس الخاصة بالمصفوفة في [2]
من أقواس معقوفة فارغة. تعرض طلبات الدفعات السمة
WriteControl،
التي توضّح كيفية تنفيذ طلبات الكتابة.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Batch requests\n\nThis document shows how to batch API calls together to reduce the number of\nconnections your client has to make. Batching can improve an application's\nefficiency by decreasing network round trips and increasing throughput.\n\nOverview\n--------\n\n\nEach connection your client makes results in a certain amount of overhead.\nThe Google Slides API supports batching to let your client place multiple\nrequest objects, each one specifying a single type of request to perform,\ninto a single batch request. A batch request can boost performance by\ncombining multiple subrequests into a single call to the server, retrieving\na single response back.\n\n\nWe encourage users to always batch multiple requests together. Here are some\nexamples of situations where you can use batching:\n\n- You've just started using the API and you have lots of data to upload.\n- You need to update metadata or properties, such as formatting, on multiple objects.\n- You need to delete many objects.\n\nLimits, authorization, \\& dependency considerations\n---------------------------------------------------\n\nHere's a list of other items to consider when employing batch updating:\n\n- Each batch request, including all subrequests, is counted as one API request toward your [usage limit](/workspace/slides/api/limits).\n- A batch request is authenticated once. This single authentication applies to all batch update objects in the request.\n- The server processes the subrequests in the same order they appear in the batch request. Latter subrequests can depend on actions taken during earlier subrequests. For example, in the same batch request, users can insert text into an existing document and then style it.\n\nBatch details\n-------------\n\n\nA batch request consists of one [batchUpdate](/workspace/slides/api/reference/rest/v1/presentations/batchUpdate) method call\nwith multiple subrequests to, for example, add and then format a presentation.\n\n\nEach request is validated before being applied. All subrequests in the batch\nupdate are applied atomically. That is, if any request is not valid then the\nentire update is unsuccessful and none of the (potentially dependent)\nchanges are applied.\n\n\nSome requests provide responses with information about the applied requests.\nFor example, all batch update requests to add objects return responses so\nyou can access the metadata of the newly added object, such as the ID or\ntitle.\n\n\nWith this approach, you can build an entire Google document using one API\nbatch update request with multiple subrequests.\n\n### Format of a batch request\n\n\nA [request](/workspace/slides/api/reference/rest/v1/presentations/request) is a single JSON request containing multiple,\nnested subrequests with one required property: `requests`. The\nrequests are constructed in an array of individual requests. Each request uses\nJSON to represent the request object and to contain its properties.\n\n### Format of a batch response\n\n\nThe [response](/workspace/slides/api/reference/rest/v1/presentations/response) format for a batch request is similar to the\nrequest format. The server's response contains a complete reply of the single\nresponse object.\n\n\nThe main JSON object's property is named `replies`. The responses\nare returned in an array, with each response to one of the requests occupying\nthe same index order as the corresponding request. Some requests don't have\nresponses and the response at that array index is empty.\n\nExample\n-------\n\nThe following code sample shows the use of batching with the\nSlides API.\n\n### Request\n\nThis example batch request demonstrates how to:\n\n- Add a\n [`presentations.pages`](/workspace/slides/api/reference/rest/v1/presentations.pages)\n resource to an existing presentation, with an `insertionIndex` of `1`, using\n the\n [`CreateSlideRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#createsliderequest)\n method.\n\n- Add a `shapeType` of type `TEXT_BOX` to the new slide using the\n [`CreateShapeRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#createshaperequest)\n method.\n\n- Insert \"Hello World\" text into the new field using the\n [`InsertTextRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#inserttextrequest)\n method.\n\n```scdoc\n{\n \"requests\":[\n {\n \"createSlide\":{\n \"insertionIndex\":1,\n \"objectId\":\"newSlide\"\n }\n },\n {\n \"createShape\":{\n \"elementProperties\":{\n \"pageObjectId\":\"newSlide\",\n \"size\":{\n \"height\":{\n \"magnitude\":50,\n \"unit\":\"PT\"\n },\n \"width\":{\n \"magnitude\":200,\n \"unit\":\"PT\"\n }\n }\n },\n \"shapeType\":\"TEXT_BOX\",\n \"objectId\":\"newTextBox\"\n }\n },\n {\n \"insertText\":{\n \"objectId\":\"newTextBox\",\n \"text\":\"Hello World\"\n }\n }\n ]\n}\n```\n\n### Response\n\nThis example batch response displays information on how each subrequest within\nthe batch request was applied. Note the\n[`InsertTextRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#inserttextrequest)\nmethod doesn't contain a response so the index value of the array at \\[2\\]\nconsists of empty curly braces. The batch request does display the\n[`WriteControl`](/workspace/slides/api/reference/rest/v1/presentations/batchUpdate#writecontrol)\nproperty, which shows how the write requests were executed. \n\n```scdoc\n{\n \"requiredRevisionId\": ID\n \"presentationId\": \"\",\n \"replies\":[\n {\n \"createSlide\":{\n \"objectId\":\"newSlide\"\n }\n },\n {\n \"createShape\":{\n \"objectId\":\"newTextBox\"\n }\n },\n {\n \n }\n ],\n \"writeControl\":{\n \"requiredRevisionId\": REVISION_ID\n }\n}\n```"]]
