בקשות אצווה

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

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה

בדוגמה הבאה מוצג שימוש באוסף בקשות עם API הדגמה כללי (פיקטיבי) שנקרא Farm API. עם זאת, אותם מושגים רלוונטיים גם ל-Compute Engine 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--