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

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

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

סקירה כללית

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

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

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

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

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

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

פרטי הקבוצה

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

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

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

בקשה באצווה היא בקשת HTTP רגילה יחידה שמכילה מספר קריאות ל-API של Google Search Console, שעושות שימוש בסוג התוכן multipart/mixed. בתוך בקשת ה-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 כללי (דמיוני) להדגמה (דמו) שנקרא Fam API. עם זאת, אותם מושגים חלים גם על Google Search Console 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--