دسته بندی درخواست های Google Analytics API

این سند نشان می‌دهد که چگونه می‌توانید تماس‌های API را با هم دسته‌بندی کنید تا تعداد اتصالات HTTP را که کلاینت‌تان باید برقرار کند، کاهش دهید.

این سند به طور خاص در مورد ایجاد یک درخواست دسته ای با ارسال یک درخواست HTTP است. اگر در عوض، از کتابخانه سرویس گیرنده Google برای درخواست دسته ای استفاده می کنید، به مستندات کتابخانه سرویس گیرنده مراجعه کنید.

بررسی اجمالی

هر اتصال HTTP مشتری شما منجر به مقدار معینی سربار می شود. Google Analytics API از دسته بندی پشتیبانی می کند تا به مشتری شما اجازه دهد چندین تماس API را در یک درخواست HTTP قرار دهد.

نمونه هایی از موقعیت هایی که ممکن است بخواهید از دسته بندی استفاده کنید:

  • به روز رسانی مجوزهای کاربر مزایای عملکرد و مشوق‌های سهمیه‌ای خاصی وجود دارد که هنگام درخواست دسته‌ای برای به‌روزرسانی مجوزهای کاربر دریافت می‌کنید، برای جزئیات به راهنمای توسعه‌دهنده مجوزهای کاربر مراجعه کنید.
  • برنامه گزارش‌دهی تلفن همراه شما ممکن است آفلاین شود، و وقتی برنامه دوباره آنلاین می‌شود، باید گروهی از درخواست‌های داده را انجام دهید.
  • شما یک برنامه حساب سرویس دارید که باید چندین گزارش را به طور منظم ایجاد کند.
  • شما باید مجموعه‌ای از ابعاد سفارشی یا معیارهای سفارشی ایجاد کنید و ترجیح می‌دهید فقط یک درخواست HTTP داشته باشید.

در هر مورد، به جای ارسال هر تماس جداگانه، می توانید آنها را در یک درخواست HTTP با هم گروه بندی کنید. همه درخواست‌های داخلی باید به همان Google API بروند.

شما به 1000 تماس در یک درخواست دسته ای محدود هستید. اگر باید بیشتر از آن تماس بگیرید، از چندین درخواست دسته ای استفاده کنید.

توجه : سیستم دسته‌ای برای Google Analytics API از همان نحوی که سیستم پردازش دسته‌ای OData استفاده می‌کند، اما معنایی متفاوت است.

جزئیات دسته

یک درخواست دسته ای شامل چندین تماس API است که در یک درخواست HTTP ترکیب شده اند، که می تواند به batchPath مشخص شده در سند کشف API ارسال شود. مسیر پیش فرض /batch/ api_name / api_version است. این بخش نحو دسته ای را به تفصیل شرح می دهد. بعداً، یک مثال وجود دارد.

توجه : مجموعه‌ای از n درخواست که با هم جمع شده‌اند به عنوان n درخواست به حساب می‌آیند، نه به عنوان یک درخواست. درخواست دسته ای قبل از پردازش به مجموعه ای از درخواست ها جدا می شود.

فرمت درخواست دسته ای

درخواست دسته‌ای یک درخواست استاندارد HTTP است که حاوی چندین تماس API Google Analytics است که از نوع محتوای multipart/mixed استفاده می‌کند. در آن درخواست اصلی HTTP، هر یک از بخش ها حاوی یک درخواست HTTP تو در تو است.

هر قسمت با هدر Content-Type: application/http HTTP. همچنین می تواند یک هدر Content-ID اختیاری داشته باشد. با این حال، سرصفحه‌های قسمت فقط برای علامت‌گذاری ابتدای قسمت وجود دارد. آنها جدا از درخواست تودرتو هستند. پس از اینکه سرور درخواست دسته ای را به درخواست های جداگانه باز می کند، سرصفحه های قسمت نادیده گرفته می شوند.

بدنه هر قسمت یک درخواست HTTP کامل است که فعل، URL، سرصفحه و بدنه خاص خود را دارد. درخواست HTTP فقط باید شامل قسمت مسیر URL باشد. URL های کامل در درخواست های دسته ای مجاز نیستند.

سرصفحه های HTTP برای درخواست دسته ای خارجی، به جز سرصفحه های Content- مانند Content-Type ، برای هر درخواست در دسته اعمال می شود. اگر یک هدر HTTP داده شده را هم در درخواست بیرونی و هم در یک تماس فردی مشخص کنید، آنگاه مقدار سرصفحه تماس منفرد بر مقدار سرصفحه درخواست دسته ای خارجی لغو می شود. سرصفحه های یک تماس فردی فقط برای آن تماس اعمال می شود.

به عنوان مثال، اگر یک سرصفحه مجوز برای یک تماس خاص ارائه کنید، آن هدر فقط برای آن تماس اعمال می شود. اگر یک سرصفحه مجوز برای درخواست خارجی ارائه دهید، آن هدر برای همه تماس‌های فردی اعمال می‌شود، مگر اینکه آن‌ها آن را با سرصفحه‌های مجوز خود لغو کنند.

هنگامی که سرور درخواست دسته‌ای را دریافت می‌کند، پارامترهای پرس و جو و هدرهای درخواست بیرونی (در صورت لزوم) را برای هر قسمت اعمال می‌کند و سپس با هر قسمت به‌گونه‌ای رفتار می‌کند که گویی یک درخواست HTTP جداگانه است.

پاسخ به درخواست دسته ای

پاسخ سرور یک پاسخ استاندارد HTTP واحد با نوع محتوای multipart/mixed است. هر قسمت پاسخ به یکی از درخواست‌های موجود در درخواست دسته‌ای است، به همان ترتیب درخواست‌ها.

مانند بخش‌های موجود در درخواست، هر بخش پاسخ شامل یک پاسخ HTTP کامل، از جمله کد وضعیت، سرصفحه‌ها و بدنه است. و مانند قسمت‌های درخواست، قبل از هر بخش پاسخ، یک هدر Content-Type وجود دارد که شروع قسمت را مشخص می‌کند.

اگر قسمت معینی از درخواست دارای هدر Content-ID باشد، قسمت مربوطه از پاسخ دارای یک سرآیند Content-ID منطبق است که مقدار اصلی قبل از string 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--

کتابخانه های مشتری

از راهنماهای کتابخانه مشتری زیر استفاده کنید تا نحوه اجرای Batching را به زبان خود مشاهده کنید:

سهمیه بچینگ و گوگل آنالیتیکس

در حالی که دسته‌بندی می‌تواند شما را در هزینه ساخت بسیاری از درخواست‌های HTTP صرفه‌جویی کند، هر درخواست Google Analytics API در یک درخواست دسته‌ای در سهمیه پروژه روزانه شما حساب می‌شود. به طور پیش فرض یک پروژه می تواند تا 50000 درخواست در روز ارائه دهد. دسته بندی به شما کمک نمی کند که زیر این سهمیه بمانید.

به استثنای درخواست‌های دسته‌ای برای نوشتن مجوزهای کاربر (حذف، درج، به‌روزرسانی) ، همه محدودیت‌های نرخ همچنان اعمال می‌شوند. برای مثال، Core Reporting API به 10 درخواست همزمان در هر نمایش (نمایه) محدود شده است. دسته بندی به شما کمک نمی کند که زیر این حد باقی بمانید.

محدودیت 1.5 پرس و جو در ثانیه (QPS) برای هر شناسه حساب برای درخواست های نوشتن API مدیریت و درخواست های نوشتن API ارائه می شود. بنابراین، دسته‌بندی این درخواست‌های نوشتن ممکن است عملکرد را بهبود نبخشد.