این سند توضیح می‌دهد که چگونه یک برنامه کاربردی می‌تواند مجوز درخواست به Tag Manager API را دریافت کند.
درخواست های مجاز
قبل از اینکه کاربران بتوانند اطلاعات حساب خود را در هر سایت Google مشاهده کنند، ابتدا باید با یک حساب Google وارد شوند. به همین ترتیب، هنگامی که کاربران برای اولین بار به برنامه شما دسترسی پیدا می کنند، باید به برنامه شما اجازه دسترسی به داده های خود را بدهند.
هر درخواستی که برنامه شما به API Tag Manager ارسال می کند باید شامل یک نشانه مجوز باشد. توکن همچنین برنامه شما را در گوگل شناسایی می کند.
درباره پروتکل های مجوز
برنامه شما باید از OAuth 2.0 برای تأیید درخواست ها استفاده کند. هیچ پروتکل مجوز دیگری پشتیبانی نمی شود. اگر برنامه شما از ورود به سیستم با Google استفاده می کند، برخی از جنبه های مجوز برای شما انجام می شود.
تأیید درخواست ها با OAuth 2.0
همه درخواست‌ها به API Tag Manager باید توسط یک کاربر تأیید شده مجاز باشد.
جزئیات فرآیند مجوز یا "جریان" برای OAuth 2.0 بسته به نوع برنامه ای که می نویسید تا حدودی متفاوت است. فرآیند کلی زیر برای همه انواع برنامه ها اعمال می شود:
- هنگامی که برنامه خود را ایجاد می کنید، آن را با استفاده از Google API Console ثبت می کنید. سپس Google اطلاعاتی را که بعداً به آن نیاز خواهید داشت، مانند شناسه مشتری و راز مشتری ارائه می دهد.
- API Tag Manager را در Google API Console فعال کنید. (اگر API در لیست API Console نیست، از این مرحله صرفنظر کنید.)
- هنگامی که برنامه شما نیاز به دسترسی به داده های کاربر دارد، از Google دامنه دسترسی خاصی را می خواهد.
- Google یک صفحه رضایت به کاربر نمایش می دهد و از او می خواهد تا به برنامه شما اجازه دهد تا برخی از داده های خود را درخواست کند.
- اگر کاربر تأیید کند، گوگل به برنامه شما یک رمز دسترسی کوتاه مدت می دهد.
- برنامه شما با پیوست کردن رمز دسترسی به درخواست، داده های کاربر را درخواست می کند.
- اگر Google تشخیص دهد که درخواست شما و رمز معتبر هستند، داده‌های درخواستی را برمی‌گرداند.
برخی از جریان‌ها شامل مراحل اضافی هستند، مانند استفاده از نشانه‌های تازه‌سازی برای به دست آوردن نشانه‌های دسترسی جدید. برای اطلاعات دقیق درباره جریان‌ها برای انواع مختلف برنامه‌ها، به اسناد OAuth 2.0 Google مراجعه کنید.
در اینجا اطلاعات محدوده OAuth 2.0 برای API Tag Manager آمده است:
| محدوده | معنی |
|---|---|
https://www.googleapis.com/auth/tagmanager.readonly | ظروف Google Tag Manager خود را مشاهده کنید. |
https://www.googleapis.com/auth/tagmanager.edit.containers | ظروف Google Tag Manager خود را مدیریت کنید. |
https://www.googleapis.com/auth/tagmanager.delete.containers | ظروف Google Tag Manager خود را حذف کنید. |
https://www.googleapis.com/auth/tagmanager.edit.containerversions | نسخه‌های ظرف Google Tag Manager خود را مدیریت کنید. |
https://www.googleapis.com/auth/tagmanager.publish | ظروف Google Tag Manager خود را منتشر کنید. |
https://www.googleapis.com/auth/tagmanager.manage.users | مجوزهای کاربر داده های Google Tag Manager خود را مدیریت کنید. |
https://www.googleapis.com/auth/tagmanager.manage.accounts | حساب‌های Google Tag Manager خود را مدیریت کنید. |
برای درخواست دسترسی با استفاده از OAuth 2.0، برنامه شما به اطلاعات محدوده و همچنین اطلاعاتی که Google هنگام ثبت برنامه خود ارائه می دهد (مانند شناسه مشتری و رمز سرویس گیرنده) نیاز دارد.
شروع شدن
برای شروع استفاده از Tag Manager API، ابتدا باید از ابزار setup استفاده کنید ، که شما را از طریق ایجاد پروژه در Google API Console، فعال کردن API و ایجاد اعتبار راهنمایی می‌کند.
برای راه اندازی یک حساب سرویس جدید، موارد زیر را انجام دهید:
- روی ایجاد اعتبارنامه > کلید حساب سرویس کلیک کنید.
- انتخاب کنید که آیا کلید عمومی/خصوصی حساب سرویس به‌عنوان فایل استاندارد P12 بارگیری شود یا به‌عنوان فایل JSON که می‌تواند توسط کتابخانه سرویس گیرنده Google API بارگیری شود.
جفت کلید عمومی/خصوصی جدید شما تولید و در دستگاه شما دانلود می شود. به عنوان تنها کپی این کلید عمل می کند. شما مسئول نگهداری ایمن آن هستید.
جریان های معمول OAuth 2.0
دستورالعمل‌های زیر موارد استفاده رایج را برای جریان‌های خاص OAuth 2.0 بیان می‌کند:
وب سرور
این جریان برای دسترسی خودکار/آفلاین/برنامه‌ریزی شده به حساب Google Tag Manager یک کاربر خوب است.
- به‌روزرسانی خودکار اطلاعات Tag Manager از یک سرور.
سمت مشتری
ایده آل برای زمانی که کاربران مستقیماً با برنامه تعامل دارند تا به حساب Google Tag Manager خود در یک مرورگر دسترسی پیدا کنند. این جریان نیاز به قابلیت های سمت سرور را از بین می برد، اما همچنین آن را برای گزارش های خودکار/آفلاین/برنامه ریزی شده غیرعملی می کند.
- یک ابزار پیکربندی مبتنی بر مرورگر سفارشی.
برنامه های نصب شده
برای برنامه هایی که به صورت بسته توزیع شده و توسط کاربر نصب می شوند. لازم است که برنامه یا کاربر برای تکمیل جریان احراز هویت به مرورگر دسترسی داشته باشد.
- ویجت دسکتاپ در رایانه شخصی یا مک.
- افزونه ای برای سیستم مدیریت محتوا. مزیت این جریان در مقایسه با وب سرور یا سمت سرویس گیرنده این است که می توان از یک پروژه کنسول API واحد برای برنامه شما استفاده کرد. این امکان نصب ساده تری را برای کاربران فراهم می کند.
حساب های خدماتی
مفید برای دسترسی خودکار/آفلاین/برنامه‌ریزی شده به حساب Google Tag Manager خودتان. به عنوان مثال، برای ایجاد یک ابزار سفارشی برای نظارت بر حساب Google Tag Manager خود و به اشتراک گذاری آن با سایر کاربران.
عیب یابی
اگر access_token شما منقضی شده باشد یا از محدوده اشتباه برای یک تماس API خاص استفاده کنید، یک کد وضعیت 401 در پاسخ دریافت می کنید.
اگر کاربر مجاز به حساب یا ظرف Google Tag Manager دسترسی نداشته باشد، کد وضعیت 403 را در پاسخ دریافت می‌کنید. اطمینان حاصل کنید که مجوز کاربر صحیح را دارید و به شما اجازه دسترسی به حساب یا محفظه Tag Manager داده شده است.
زمین بازی OAuth 2.0
OAuth 2.0 Playground به شما امکان می دهد کل جریان مجوز را از طریق یک رابط وب طی کنید. این ابزار همچنین تمام هدرهای درخواست HTTP مورد نیاز برای ایجاد یک پرس و جو مجاز را نمایش می دهد. اگر نمی توانید مجوز کار در برنامه خود را دریافت کنید، باید سعی کنید از طریق OAuth 2.0 Playground کار کنید. سپس می‌توانید هدرهای HTTP را مقایسه کنید و از زمین بازی با آنچه برنامه شما ارسال می‌کند درخواست کنید. این بررسی یک راه ساده برای اطمینان از اینکه درخواست های خود را به درستی قالب بندی می کنید است.
کمک هزینه نامعتبر
اگر هنگام تلاش برای استفاده از نشانه رفرش، پاسخ خطای invalid_grant دریافت کردید، ممکن است این خطا به دلیل یکی از موارد زیر باشد:
- ساعت سرور شما با NTP همگام نیست.
- شما از حد مجاز نشانه بازخوانی فراتر رفته اید.
برنامه‌ها می‌توانند برای دسترسی به یک حساب Google Tag Manager، چندین توکن به‌روزرسانی درخواست کنند. به عنوان مثال، این در شرایطی مفید است که کاربر می‌خواهد یک برنامه را روی چندین ماشین نصب کند و به همان حساب Google Tag Manager دسترسی پیدا کند. در این مورد، دو نشانه رفرش لازم است، یکی برای هر نصب. وقتی تعداد نشانه‌های تازه‌سازی از حد مجاز بیشتر شود، نشانه‌های قدیمی‌تر نامعتبر می‌شوند. اگر برنامه سعی کند از یک نشانه رفرش نامعتبر استفاده کند، یک پاسخ خطایinvalid_grantبرگردانده می شود. هر ترکیب منحصربه‌فرد شناسه مشتری/حساب می‌تواند تا 25 توکن به‌روزرسانی داشته باشد. (توجه داشته باشید که این محدودیت ممکن است تغییر کند.) اگر برنامه همچنان برای همان ترکیب Client-ID/حساب درخواست نشانه های تازه سازی کند، پس از صدور بیست و ششمین توکن، اولین نشانه به روز رسانی صادر شده نامعتبر می شود. بیست و هفتمین توکن درخواستی رفرش، دومین توکن صادر شده را باطل می کند و غیره.