בקשות אצווה

ב-12 באוגוסט 2020 הכרזנו על נקודת סיום ספציפית אחת לאצווה (Global HTTP Batch), כפי שהיא פורסמה בבלוג Google Developers. גישות אחרות לקיבוץ עדיין פועלות, כפי שמתואר בשאר הדף. אם הקוד שלכם משתמש בנקודת הקצה הגלובלית HTTP HTTP, תוכלו לעיין בפוסט בבלוג עם הוראות למעבר לשימוש בגישות אחרות, כמו נקודות קצה (endpoints) של HTTP ספציפי ל-API www.googleapis.com/batch/API/VERSION.

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

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

סקירה כללית

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

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

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

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

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

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

פרטי אצווה

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

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

פורמט של בקשה לקיבוץ

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

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

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

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

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

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

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

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

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

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

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

דוגמה

בדוגמה הבאה מוצגים שימוש באצוות עם Google Mirror API.

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

POST /batch HTTP/1.1
Content-Length: content_length
content-type: multipart/mixed; boundary="===============7330845974216740156=="
accept-encoding: gzip, deflate

--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_1

POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_1_token
accept: application/json
content-length: 24

{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_2

POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_2_token
accept: application/json
content-length: 24

{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_3

POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_3_token
accept: application/json
content-length: 24

{"text": "Hello there!"}
--===============7330845974216740156==--

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

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

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Date: Tue, 22 Jan 2013 18:56:00 GMT
Expires: Tue, 22 Jan 2013 18:56:00 GMT
Cache-Control: private, max-age=0

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_1

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304

{
 "kind": "glass#timelineItem",
 "id": "1234567890",
 "selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890",
 "created": "2012-09-25T23:28:43.192Z",
 "updated": "2012-09-25T23:28:43.192Z",
 "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
 "text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_2

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304

{
 "kind": "glass#timelineItem",
 "id": "0987654321",
 "selfLink": "https://www.googleapis.com/mirror/v1/timeline/0987654321",
 "created": "2012-09-25T23:28:43.192Z",
 "updated": "2012-09-25T23:28:43.192Z",
 "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
 "text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_3

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304

{
 "kind": "glass#timelineItem",
 "id": "5432109876",
 "selfLink": "https://www.googleapis.com/mirror/v1/timeline/5432109876",
 "created": "2012-09-25T23:28:43.192Z",
 "updated": "2012-09-25T23:28:43.192Z",
 "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
 "text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--