این راهنما نحوهی تأیید درخواستها به API حذف کاربر توسط یک برنامه را شرح میدهد.
درخواستها را تأیید کنید
قبل از اینکه کاربران بتوانند اطلاعات حساب خود را در وبسایت گوگل آنالیتیکس مشاهده کنند، ابتدا باید وارد حسابهای گوگل خود شوند. به طور مشابه، وقتی کاربران برای اولین بار به برنامه شما دسترسی پیدا میکنند، باید به برنامه شما اجازه دسترسی به دادههای خود را بدهند.
هر درخواستی که برنامه شما به API آنالیتیکس ارسال میکند، باید شامل یک توکن مجوز باشد. این توکن همچنین برنامه شما را به گوگل معرفی میکند.
درباره پروتکلهای مجوزدهی
برنامه شما باید از OAuth 2.0 برای تأیید درخواستها استفاده کند. هیچ پروتکل تأیید دیگری پشتیبانی نمیشود. اگر برنامه شما از ورود با گوگل استفاده میکند، برخی از جنبههای تأیید برای شما انجام میشود.
تأیید درخواستها با OAuth 2.0
تمام درخواستها به API آنالیتیکس باید توسط یک کاربر احراز هویت شده تأیید شوند.
جزئیات فرآیند مجوزدهی یا «جریان» برای OAuth 2.0 بسته به نوع برنامهای که مینویسید تا حدودی متفاوت است. فرآیند کلی زیر برای همه انواع برنامه اعمال میشود:
- وقتی برنامه خود را ایجاد میکنید، آن را با استفاده از کنسول API گوگل ثبت میکنید. سپس گوگل اطلاعاتی را که بعداً به آنها نیاز خواهید داشت، مانند شناسه کلاینت و رمز کلاینت، در اختیار شما قرار میدهد.
- API مربوط به Analytics را در کنسول API گوگل فعال کنید. (اگر API در کنسول API فهرست نشده است، از این مرحله صرف نظر کنید.)
- وقتی برنامه شما نیاز به دسترسی به دادههای کاربر دارد، از گوگل درخواست محدوده خاصی از دسترسی را میکند.
- گوگل یک صفحه رضایتنامه به کاربر نمایش میدهد و از او میخواهد که به برنامه شما اجازه دهد تا برخی از دادههایش را درخواست کند.
- اگر کاربر تأیید کند، گوگل یک توکن دسترسی کوتاهمدت به برنامه شما میدهد.
- برنامه شما دادههای کاربر را درخواست میکند و توکن دسترسی را به درخواست پیوست میکند.
- اگر گوگل تشخیص دهد که درخواست شما و توکن معتبر هستند، دادههای درخواستی را برمیگرداند.
برخی از جریانها شامل مراحل اضافی مانند استفاده از توکنهای تازهسازی برای به دست آوردن توکنهای دسترسی جدید هستند. برای اطلاعات دقیق در مورد جریانها برای انواع مختلف برنامهها، به مستندات OAuth 2.0 گوگل مراجعه کنید.
اطلاعات مربوط به محدودهی OAuth 2.0 برای Analytics API به شرح زیر است:
| دامنه | معنی |
|---|---|
https://www.googleapis.com/auth/analytics.user.deletion | حذف دادهها با استفاده از رابط برنامهنویسی کاربردی حذف کاربر. |
برای درخواست دسترسی با استفاده از OAuth 2.0، برنامه شما به اطلاعات دامنه و همچنین اطلاعاتی که گوگل هنگام ثبت برنامه شما ارائه میدهد (مانند شناسه کلاینت و رمز کلاینت) نیاز دارد.
نکته: کتابخانههای کلاینت APIهای گوگل میتوانند بخشی از فرآیند مجوزدهی را برای شما انجام دهند. این کتابخانهها برای زبانهای برنامهنویسی مختلفی در دسترس هستند؛ برای جزئیات بیشتر ، صفحه مربوط به کتابخانهها و نمونهها را بررسی کنید.
جریانهای رایج OAuth 2.0
موارد استفاده رایج برای جریانهای خاص OAuth 2.0 در زیر فهرست شدهاند:
وب سرور
این جریان برای دسترسی خودکار، آفلاین یا برنامهریزیشده به دادههای گوگل آنالیتیکس کاربر مناسب است.
مثال:
- بهروزرسانی خودکار داشبوردهای کاربران با جدیدترین دادههای گوگل آنالیتیکس.
سمت کلاینت
این جریان برای برنامههایی ایدهآل است که کاربران مستقیماً با برنامه تعامل دارند تا به دادههای گوگل آنالیتیکس خود در یک مرورگر دسترسی پیدا کنند. این امر نیاز به قابلیتهای سمت سرور را از بین میبرد، اما گزارشدهی خودکار، آفلاین یا برنامهریزیشده را غیرعملی میکند.
مثال:
- یک ابزار گزارشدهی مبتنی بر مرورگر مانند Analytics Query Explorer .
برنامههای نصبشده
این جریان برای برنامههایی است که به صورت بسته توزیع شده و توسط کاربر نصب میشوند. این جریان مستلزم آن است که برنامه یا کاربر برای تکمیل جریان احراز هویت به یک مرورگر دسترسی داشته باشند.
مثالها:
- یک ویجت دسکتاپ روی کامپیوتر شخصی یا مک.
- افزونهای برای سیستم مدیریت محتوا - مزیت این جریان در مقایسه با وب سرور یا سمت کلاینت این است که میتوان از یک پروژه API Console برای برنامه شما استفاده کرد. این امر امکان گزارشگیری یکپارچه و نصب سادهتر را برای کاربران فراهم میکند.
حسابهای خدماتی
حسابهای سرویس برای دسترسی خودکار، آفلاین یا زمانبندیشده به دادههای گوگل آنالیتیکس برای حساب کاربری خودتان مفید هستند. به عنوان مثال، برای ساخت یک داشبورد زنده از دادههای گوگل آنالیتیکس خودتان و به اشتراکگذاری آن با سایر کاربران.
برای شروع استفاده از Analytics API، ابتدا باید از ابزار راهاندازی استفاده کنید که شما را در ایجاد یک پروژه در کنسول Google API و فعال کردن API راهنمایی میکند.
برای تنظیم یک حساب کاربری سرویس جدید، موارد زیر را انجام دهید:
- روی ایجاد اعتبارنامهها > کلید حساب سرویس کلیک کنید.
- انتخاب کنید که آیا کلید عمومی/خصوصی حساب سرویس را به عنوان یک فایل استاندارد P12 دانلود کنید یا به عنوان یک فایل JSON که میتواند توسط یک کتابخانه کلاینت Google API بارگذاری شود.
جفت کلید عمومی/خصوصی جدید شما تولید و در دستگاه شما دانلود میشود؛ این جفت کلید به عنوان تنها کپی از این کلید عمل میکند. شما مسئول ذخیره ایمن آن هستید.
عیبیابی
مجوز شما در این شرایط ناموفق است:
اگر
access_tokenشما منقضی شده باشد یا اگر از scope اشتباهی برای API استفاده میکنید، کد وضعیت401دریافت خواهید کرد.اگر کاربر مجاز به نمای (پروفایل) دسترسی نداشته باشد، کد وضعیت
403دریافت خواهید کرد. مطمئن شوید که با کاربر صحیح مجاز شدهاید و او واقعاً نمای (پروفایل) انتخابی شما را دارد.
زمین بازی OAuth 2.0
این ابزار به شما امکان میدهد کل جریان مجوزدهی را از طریق یک رابط وب بررسی کنید. این ابزار همچنین تمام هدرهای درخواست HTTP مورد نیاز برای ایجاد یک پرسوجوی مجاز را نمایش میدهد. اگر نمیتوانید مجوز کار را در برنامه خود دریافت کنید، باید سعی کنید آن را از طریق playground OAuth 2.0 فعال کنید. سپس میتوانید هدرهای HTTP و درخواست از playground را با آنچه برنامه شما به Google Analytics ارسال میکند مقایسه کنید. این بررسی روشی ساده برای اطمینان از قالببندی صحیح درخواستهای شما است.
کمک هزینه نامعتبر
وقتی سعی میکنید از یک توکن refresh استفاده کنید، کد زیر خطای invalid_grant را برمیگرداند:
- ساعت سرور شما با پروتکل زمان شبکه - NTP - هماهنگ نیست.
- محدودیت توکن بهروزرسانی (refresh token) از حد مجاز فراتر رفته است.
برنامهها میتوانند برای دسترسی به یک حساب گوگل آنالیتیکس، چندین توکن رفرش درخواست کنند.
برای مثال، اگر کاربری بخواهد برنامهای را روی چندین دستگاه نصب کند و به یک حساب گوگل آنالیتیکس دسترسی داشته باشد، برای هر دستگاه یک توکن جداگانه لازم است. وقتی تعداد توکنهای بهروزرسانی از حد مجاز فراتر رود، توکنهای قدیمیتر نامعتبر میشوند. اگر برنامه سعی کند از یک توکن بهروزرسانی نامعتبر استفاده کند، پاسخ خطای invalid_grant بازگردانده میشود.
محدودیت برای هر جفت منحصر به فرد از کلاینت OAuth 2.0 و حساب Google Analytics، ۲۵ توکن بهروزرسانی است. اگر برنامه به درخواست توکنهای بهروزرسانی برای همان جفت کلاینت/حساب ادامه دهد، پس از صدور بیست و ششمین توکن، اولین توکن بهروزرسانی که قبلاً صادر شده بود، نامعتبر خواهد شد. بیست و هفتمین توکن بهروزرسانی درخواستی، دومین توکن صادر شده قبلی را نامعتبر میکند و به همین ترتیب ادامه مییابد.