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

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

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

סקירה כללית

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

דוגמה לבקשה בכמות גדולה

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. לכן, קיבוץ בקשות הכתיבה האלה עשוי שלא לשפר את הביצועים.