שליחת בקשות באצווה

בגרסה הזו של ה-API, רק העברת המינוי משתמשת בבקשה באצווה. בנוסף, השדה Content-ID באצווה לא מאוכלס בבקשה באצווה של ה-API.

במסמך הזה נסביר איך לקבץ באצווה קריאות ל-API כדי לצמצם את מספר חיבורי ה-HTTP. שהלקוח צריך לבצע.

המסמך הזה עוסק ספציפית בשליחת בקשה באצווה על ידי שליחת בקשת HTTP. אם אתם משתמשים בספריית לקוח של Google כדי לשלוח בקשה באצווה, כדאי לעיין במסמכי התיעוד של ספריית הלקוח.

סקירה כללית

כל חיבור HTTP שהלקוח יוצר מגדיל במידה מסוימת את התקורה. ה-Admin SDK API תומך בקיבוץ באצווה של קריאות כדי לאפשר ללקוח לבצע מספר קריאות ל-API בבקשת HTTP אחת.

דוגמאות למצבים שבהם כדאי להשתמש בקיבוץ באצווה של קריאות:

• רק התחלתם להשתמש ב-API ויש לכם המון נתונים להעלות.
• משתמש ביצע שינויים בנתונים בזמן שהאפליקציה הייתה במצב אופליין (מנותק מהאינטרנט), לכן האפליקציה שלכם צריכה לסנכרן את הנתונים המקומיים שלה עם השרת על ידי שליחת כמות גדולה של עדכונים ומחיקה.

במקרים כאלה, במקום לשלוח כל קריאה בנפרד, אפשר לקבץ את כל הקריאות בבקשת HTTP אחת. כל הבקשות הפנימיות חייבות לעבור לאותו Google API.

בבקשה באצווה אחת אפשר לכלול עד 1,000 קריאות. אם צריך לבצע יותר קריאות, תוכלו להשתמש במספר בקשות באצווה.

הערה: התחביר של המערכת באצווה של Admin SDK API זהה לזה של מערכת עיבוד אצווה של OData, אבל הסמנטיקה שונה.

פירוט לגבי בקשות באצווה

בקשה באצווה מורכבת מכמה קריאות ל-API המאוגדות לבקשת HTTP אחת, שאותה אפשר לשלוח אל ה-batchPath שצוין במסמך ה-Discovery של ה-API. נתיב ברירת המחדל הוא /batch/api_name/api_version. הקטע הזה מתאר בפירוט את התחביר של קריאות באצווה; בהמשך, יש דוגמה.

הערה: קבוצה של n בקשות מקובצות יחד נספרת כדי לחשב את מגבלת השימוש כבקשות n, ולא כבקשה אחת. הבקשה באצווה מופרדת לקבוצה של בקשות לפני העיבוד.

הפורמט של בקשה באצווה

בקשה באצווה היא בקשת HTTP רגילה יחידה שמכילה כמה קריאות ל-Admin SDK API, באמצעות סוג התוכן multipart/mixed. בבקשת ה-HTTP הראשית, כל אחד מהחלקים מכיל בתוכו בקשת HTTP פנימית.

כל חלק מתחיל בכותרת HTTP ‏Content-Type: application/http משלו. אפשר להוסיף לה גם כותרת Content-ID אופציונלית. עם זאת, כותרות החלקים רק נועדו לסמן את תחילת החלק. הם נפרדים מהבקשה הפנימית. אחרי שהשרת מפרק את הבקשה באצווה לבקשות נפרדות, המערכת מתעלמת מכותרות החלקים.

הגוף של כל חלק הוא בקשת HTTP מלאה עם פועל, כתובת URL, כותרות וגוף. בקשת ה-HTTP חייבת להכיל רק את החלק של הנתיב שבכתובת ה-URL. כתובות URL מלאות אינן מותרות בבקשות באצווה.

כותרות ה-HTTP של הבקשה החיצונית המקובצת באצווה חלות על כל בקשה באצווה, מלבד כותרות Content-, כמו Content-Type. אם תציינו כותרת HTTP ספציפית בבקשה החיצונית המקובצת וגם בקריאה ספציפית, הערך של כותרת הקריאה הספציפית יבטל את הערך של כותרת הבקשה החיצונית באצווה. הכותרות של שיחות ספציפיות חלות רק על אותה שיחה.

לדוגמה, אם מציינים כותרת Authorization לשיחה ספציפית, הכותרת חלה רק על השיחה הזו. אם מציינים כותרת הרשאה בבקשה החיצונית, הכותרת תחול על כל הקריאות הנפרדות, אלא אם הן יבטלו אותה באמצעות כותרות הרשאות משלהן.

כשהשרת מקבל את הבקשה באצווה, הוא מחיל את הפרמטרים והכותרות של השאילתה החיצונית (לפי הכללים) על כל חלק, ולאחר מכן מתייחס לכל חלק כאילו היה בקשת HTTP נפרדת.

תשובה לבקשה באצווה

תגובת השרת היא תגובת HTTP רגילה יחידה עם סוג תוכן multipart/mixed. כל חלק הוא התשובה לאחת מהבקשות שבבקשה באצווה, באותו סדר כמו הבקשות.

בדומה לחלקים בבקשה, כל חלק בתשובה מכיל תגובת HTTP מלאה, כולל קוד סטטוס, כותרות וגוף. בדומה לחלקים שבבקשה, לפני כל חלק של תשובה מופיעה כותרת Content-Type שמסמנת את תחילת החלק.

אם לחלק מסוים בבקשה יש כותרת Content-ID, לחלק המתאים בתשובה יש כותרת Content-ID תואמת, עם הערך המקורי לפני המחרוזת response-, כמו בדוגמה הבאה.

הערה: השרת עשוי לבצע את הקריאות לפי סדר שאינו קבוע מראש. אל תסתמכו על כך שהן יבוצעו לפי הסדר שבו ציינתם אותן. אם רוצים להבטיח ששתי קריאות יתבצעו בסדר מסוים, אי אפשר לשלוח אותן בבקשה אחת. במקום זאת, צריך לשלוח את ההודעה הראשונה בנפרד, ואז להמתין לתשובה הראשונה לפני ששולחים את השנייה.

דוגמה

בדוגמה הבאה מוצג השימוש בקיבוץ באצווה באמצעות Admin SDK API.

דוגמה לבקשה באצווה

/*This example uses comments and variables for clarity.*/
/*These are not used in JSON. Do not include these comments or verbatim*/
/*variable strings in your batch request.*/
/*To batch multiple requests in one call, use the following*/
/*                                                         */
/*POST HTTP request, and use the following request body syntax.*/
/*                                                  */
/*POST https://www.googleapis.com/batch*/

--batch_foobar-- 

דוגמה לתשובה באצווה

זוהי התשובה לבקשה לדוגמה שבקטע הקודם.

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:[e-mail]>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:[e-mail]>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:[e-mail]>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--