קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
במאמר הזה נסביר איך לקבץ באצווה קריאות ל-API כדי לצמצם את מספר החיבורים שהלקוח צריך לבצע. הוספת פעולות לאצווה יכולה לשפר את היעילות של אפליקציה על ידי הקטנת מספר הנסיעות הלוך ושוב ברשת והגדלת קצב העברת הנתונים.
סקירה כללית
כל חיבור שהלקוח יוצר מגדיל במידה מסוימת את התקורה.
ה-API של Google Slides תומך בקיבוץ באצווה של קריאות כדי לאפשר ללקוח לבצע מספר אובייקטים של בקשות, שכל אחד מהם מציין סוג יחיד של בקשה לביצוע, בבקשה אחת באצווה. בקשה לאצווה יכולה לשפר את הביצועים כי היא משלבת כמה בקשות משנה לקריאה אחת לשרת, ומקבלת תשובה אחת.
אנחנו ממליצים למשתמשים תמיד לאגד כמה בקשות יחד. הנה כמה דוגמאות למצבים שבהם כדאי להשתמש בקיבוץ באצווה של קריאות:
רק התחלתם להשתמש ב-API ויש לכם הרבה נתונים להעלות.
צריך לעדכן מטא-נתונים או מאפיינים, כמו עיצוב, בכמה אובייקטים.
צריך למחוק הרבה אובייקטים.
שיקולים לגבי מגבלות, הרשאות ותלות
ריכזנו כאן רשימה של פריטים נוספים שכדאי לקחת בחשבון כשמשתמשים בעדכון אצווה:
כל בקשה באצווה, כולל כל בקשות המשנה, נספרת כבקשת API אחת במגבלת השימוש.
בקשה אחת מאמתת את כל הבקשות בקבוצה. האימות הזה חל על כל האובייקטים של עדכון באצווה בבקשה.
השרת מעבד את בקשות המשנה באותו סדר שבו הן מופיעות בבקשה מרובת הפעולות. בקשות משנה מאוחרות יותר יכולות להיות תלויות בפעולות שבוצעו במהלך בקשות משנה קודמות. לדוגמה, באותה בקשת אצווה, המשתמשים יכולים להוסיף טקסט למסמך קיים ואז לעצב אותו.
פירוט לגבי בקשות באצווה
בקשה באצווה מורכבת מקריאה אחת לשיטת batchUpdate עם כמה בקשות משנה, למשל כדי להוסיף מצגת ואז לעצב אותה.
כל בקשה עוברת אימות לפני שהיא מיושמת. כל בקשות המשנה בעדכון
הקבוצתי מוחלות באופן אטומי. כלומר, אם בקשה כלשהי לא תקינה, העדכון כולו ייכשל ואף אחד מהשינויים (שעשויים להיות תלויים זה בזה) לא יחול.
חלק מהבקשות מספקות תשובות עם מידע על הבקשות שהוגשו.
לדוגמה, כל בקשות העדכון באצווה להוספת אובייקטים מחזירות תגובות, כך שאפשר לגשת למטא-נתונים של האובייקט שנוסף, כמו המזהה או השם.
בגישה הזו, אפשר ליצור מסמך שלם ב-Google באמצעות בקשת עדכון באצווה של API עם כמה בקשות משנה.
הפורמט של בקשה באצווה
בקשה היא בקשת JSON אחת שמכילה כמה בקשות משנה מקוננות עם מאפיין חובה אחד: requests. הבקשות מורכבות ממערך של בקשות נפרדות. כל בקשה משתמשת ב-JSON כדי לייצג את אובייקט הבקשה וכדי להכיל את המאפיינים שלו.
הפורמט של תשובה לבקשה באצווה
הפורמט של תשובה לבקשה באצווה דומה לפורמט של הבקשה. התגובה של השרת מכילה תשובה מלאה של אובייקט התשובה היחיד.
המאפיין של אובייקט ה-JSON הראשי נקרא replies. התשובות מוחזרות במערך, וכל תשובה לאחת מהבקשות תופסת את אותו סדר אינדקס כמו הבקשה התואמת. חלק מהבקשות לא מקבלות תשובות, והתשובה באינדקס הזה במערך ריקה.
דוגמה
בדוגמת הקוד הבאה מוצג שימוש באוסף בקשות עם Slides API.
בתשובה הזו לבקשה באצווה מוצג מידע על האופן שבו כל בקשת משנה בתוך הבקשה באצווה הוחלה. שימו לב שהשיטה
InsertTextRequest
לא מכילה תגובה, ולכן ערך האינדקס של המערך ב-[2]
מורכב מסוגריים מסולסלים ריקים. בבקשה הקבוצתית מוצג המאפיין
WriteControl
שמראה איך בוצעו בקשות הכתיבה.
[[["התוכן קל להבנה","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 (שעון UTC)."],[],[],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```"]]
