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

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

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

סקירה כללית

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

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

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

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

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

הערה: מערכת הקריאות באצווה של Enterprise License Manager API משתמשת בתחביר זהה לזה של מערכת העיבוד ברצף (batch processing) של OData, אבל הסמנטיקה שלהן שונה.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

בדוגמה הבאה תוכלו לראות את השימוש בקיבוץ באצווה של API להדגמה (דמו) כללי (פיקטיבי) שנקרא לעתים קרובות API של החווה. עם זאת, אותם מושגים חלים על Enterprise License Manager API.

דוגמה לבקשת Batch

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

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

GET /farm/v1/animals/pony

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

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

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

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

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

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

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--