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

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

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

סקירה כללית

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

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

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

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

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

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

פרטי אצווה

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

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

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

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