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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

בקשה באצווה היא בקשת HTTP רגילה יחידה שמכילה כמה קריאות ל-Directory 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-, כמו בדוגמה הבאה.

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

דוגמה

בדוגמה הבאה מוצג השימוש בקיבוץ באצווה באמצעות API להדגמה (דמו) כללי (פיקטיבי) שנקרא Fan API. עם זאת, אותם מושגים רלוונטיים ל-Directory 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:12930812@barnyard.example.com>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:12930812@barnyard.example.com>

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:12930812@barnyard.example.com>

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:12930812@barnyard.example.com>

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:12930812@barnyard.example.com>

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:12930812@barnyard.example.com>

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

--batch_foobarbaz--