קיבוץ בקשות של Google Analytics API

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

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

סקירה

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

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

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

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

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

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

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

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

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

בקשה באצווה היא בקשת HTTP רגילה יחידה שמכילה מספר קריאות ל-API של Google Analytics, המשתמשות בסוג התוכן 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-, כפי שמוצג בדוגמה הבאה.

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

דוגמה

הדוגמה הבאה מציגה את השימוש בקיבוץ באמצעות Google Analytics API.

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

POST /batch/analytics/v3 HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68


{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67


{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

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

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

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

ספריות לקוח

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

אצווה ומכסה של Google Analytics

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

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

המגבלה של 1.5 שאילתות לשנייה (QPS) לכל מספר חשבון חלה על בקשות כתיבה ל-Management API ועל הקצאת בקשות לכתיבה ל-API. לכן, יכול להיות שקיבוץ בקשות הכתיבה האלה לא ישפר את הביצועים.