این سند توضیح میدهد که چگونه برنامههای وب سرور از Google API Client Libraries یا Google OAuth 2.0 برای اجرای مجوز OAuth 2.0 برای دسترسی به YouTube Analytics API یا YouTube Reporting API استفاده میکنند.
OAuth 2.0 به کاربران اجازه می دهد تا داده های خاصی را با یک برنامه به اشتراک بگذارند در حالی که نام کاربری، رمز عبور و سایر اطلاعات خود را خصوصی نگه می دارند. به عنوان مثال، یک برنامه می تواند از OAuth 2.0 برای دریافت مجوز برای بازیابی داده های YouTube Analytics یک کانال استفاده کند.
این جریان OAuth 2.0 به طور خاص برای مجوز کاربر است. این برای برنامه هایی طراحی شده است که می توانند اطلاعات محرمانه را ذخیره کرده و وضعیت را حفظ کنند. یک برنامه وب سرور مجاز به درستی می تواند به یک API دسترسی داشته باشد در حالی که کاربر با برنامه تعامل دارد یا بعد از اینکه کاربر برنامه را ترک کرد.
برنامههای کاربردی وب سرور اغلب از حسابهای سرویس برای تأیید درخواستهای API استفاده میکنند، بهویژه زمانی که برای دسترسی به دادههای مبتنی بر پروژه بهجای دادههای خاص کاربر، APIهای Cloud را فراخوانی میکنند. برنامه های کاربردی وب سرور می توانند از حساب های خدماتی در ارتباط با مجوز کاربر استفاده کنند.
- YouTube Analytics API از جریان حساب سرویس پشتیبانی نمی کند.
- YouTube Reporting API فقط از جریان حساب سرویس برای دارندگان محتوای YouTube که چندین کانال YouTube را مالک و مدیریت می کنند پشتیبانی می کند. به طور خاص، صاحبان محتوا میتوانند از حسابهای سرویس در درخواستهای API استفاده کنند که مقداری را برای پارامتر درخواست
onBehalfOfContentOwner
تعیین میکنند.
نمونههای مخصوص زبان در این صفحه از کتابخانههای سرویس گیرنده Google API برای اجرای مجوز OAuth 2.0 استفاده میکنند. برای اجرای نمونه کد، ابتدا باید کتابخانه کلاینت را برای زبان خود نصب کنید.
وقتی از Google API Client Library برای مدیریت جریان OAuth 2.0 برنامه خود استفاده می کنید، کتابخانه سرویس گیرنده اقدامات زیادی را انجام می دهد که در غیر این صورت برنامه به تنهایی باید آنها را مدیریت کند. برای مثال، تعیین میکند که برنامه چه زمانی میتواند از نشانههای دسترسی ذخیرهشده یا بازخوانی آن استفاده کند و همچنین زمانی که برنامه باید مجدداً رضایت خود را دریافت کند. کتابخانه مشتری همچنین URLهای تغییر مسیر صحیحی را تولید می کند و به پیاده سازی کنترل کننده های تغییر مسیر که کدهای مجوز را برای توکن های دسترسی مبادله می کنند، کمک می کند.
کتابخانه های Google API Client برای برنامه های سمت سرور برای زبان های زیر در دسترس هستند:
هر برنامهای که APIهای Google را فراخوانی میکند باید آن APIها را در API Consoleفعال کند.
برای فعال کردن یک API برای پروژه خود:
- Open the API Library در Google API Console.
- If prompted, select a project, or create a new one.
- از صفحه کتابخانه برای یافتن و فعال کردن API YouTube Analytics و YouTube Reporting API استفاده کنید. بسیاری از برنامههایی که دادههای YouTube Analytics را بازیابی میکنند، با YouTube Data API نیز ارتباط دارند. هر API دیگری را که برنامه شما از آن استفاده می کند پیدا کنید و آن ها را نیز فعال کنید.
هر برنامهای که از OAuth 2.0 برای دسترسی به APIهای Google استفاده میکند، باید دارای اعتبارنامه مجوز باشد که برنامه را در سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اعتبار برای پروژه خود را توضیح می دهد. سپس برنامه های شما می توانند از اعتبارنامه ها برای دسترسی به API هایی که برای آن پروژه فعال کرده اید استفاده کنند.
- Go to the Credentials page.
- روی ایجاد اعتبار > شناسه مشتری OAuth کلیک کنید.
- نوع برنامه کاربردی وب را انتخاب کنید.
- فرم را پر کنید و روی ایجاد کلیک کنید. برنامه هایی که از زبان ها و فریم ورک هایی مانند PHP، جاوا، پایتون، روبی و دات نت استفاده می کنند باید URI های مجاز تغییر مسیر را مشخص کنند. URI های تغییر مسیر، نقاط پایانی هستند که سرور OAuth 2.0 می تواند پاسخ ها را به آنها ارسال کند. این نقاط پایانی باید از قوانین اعتبارسنجی Google پیروی کنند.
برای آزمایش، می توانید URI هایی را مشخص کنید که به ماشین محلی اشاره می کنند، مانند
http://localhost:8080
. با در نظر گرفتن این موضوع، لطفاً توجه داشته باشید که همه نمونههای این سند ازhttp://localhost:8080
به عنوان URI تغییر مسیر استفاده میکنند.توصیه می کنیم نقاط پایانی تأیید اعتبار برنامه خود را طوری طراحی کنید که برنامه شما کدهای مجوز را در معرض سایر منابع موجود در صفحه قرار ندهد.
پس از ایجاد اطلاعات کاربری خود، فایل client_secret.json را از API Consoleدانلود کنید. فایل را در مکانی ایمن ذخیره کنید که فقط برنامه شما بتواند به آن دسترسی داشته باشد.
Scopes به برنامه شما امکان میدهد فقط درخواست دسترسی به منابع مورد نیاز خود را داشته باشد در حالی که کاربران را قادر میسازد تا میزان دسترسی را که به برنامه شما میدهند کنترل کنند. بنابراین، ممکن است بین تعداد دامنه های درخواستی و احتمال کسب رضایت کاربر رابطه معکوس وجود داشته باشد.
قبل از شروع اجرای مجوز OAuth 2.0، توصیه میکنیم محدودههایی را که برنامه شما برای دسترسی به آنها نیاز به مجوز دارد، شناسایی کنید.
ما همچنین توصیه میکنیم که برنامه شما از طریق یک فرآیند مجوز افزایشی ، که در آن برنامه شما درخواست دسترسی به دادههای کاربر در زمینه را دارد، درخواست دسترسی به دامنههای مجوز دهد. این بهترین روش به کاربران کمک می کند تا راحت تر بفهمند که چرا برنامه شما به دسترسی درخواستی نیاز دارد.
YouTube Analytics API از حوزه های زیر استفاده می کند:
محدوده ها | |
---|---|
https://www.googleapis.com/auth/youtube | حساب YouTube خود را مدیریت کنید |
https://www.googleapis.com/auth/youtube.readonly | حساب YouTube خود را مشاهده کنید |
https://www.googleapis.com/auth/youtubepartner | دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | گزارش های YouTube Analytics پولی و غیرپولی را برای محتوای YouTube خود مشاهده کنید |
https://www.googleapis.com/auth/yt-analytics.readonly | گزارشات YouTube Analytics را برای محتوای YouTube خود مشاهده کنید |
YouTube Reporting API از حوزه های زیر استفاده می کند:
محدوده ها | |
---|---|
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | گزارش های YouTube Analytics پولی و غیرپولی برای محتوای YouTube خود مشاهده کنید |
https://www.googleapis.com/auth/yt-analytics.readonly | گزارشات YouTube Analytics را برای محتوای YouTube خود مشاهده کنید |
سند OAuth 2.0 API Scopes حاوی فهرست کاملی از حوزههایی است که ممکن است برای دسترسی به Google API از آنها استفاده کنید.
برای اجرای هر یک از نمونه کدهای موجود در این سند، به یک حساب Google، دسترسی به اینترنت و یک مرورگر وب نیاز دارید. اگر از یکی از کتابخانه های سرویس گیرنده API استفاده می کنید، شرایط خاص زبان را نیز در زیر ببینید.
مراحل زیر نشان می دهد که چگونه برنامه شما با سرور OAuth 2.0 Google برای کسب رضایت کاربر برای انجام یک درخواست API از طرف کاربر تعامل دارد. برنامه شما قبل از اینکه بتواند یک درخواست Google API را که نیاز به مجوز کاربر دارد، اجرا کند، باید این رضایت را داشته باشد.
لیست زیر به سرعت این مراحل را خلاصه می کند:
- برنامه شما مجوزهای مورد نیاز خود را شناسایی می کند.
- برنامه شما کاربر را به همراه لیست مجوزهای درخواستی به Google هدایت می کند.
- کاربر تصمیم می گیرد که آیا مجوزها را به برنامه شما اعطا کند یا خیر.
- برنامه شما متوجه می شود که کاربر چه تصمیمی گرفته است.
- اگر کاربر مجوزهای درخواستی را اعطا کرده باشد، برنامه شما نشانه های مورد نیاز برای درخواست های API را از طرف کاربر بازیابی می کند.
اولین قدم شما ایجاد درخواست مجوز است. این درخواست پارامترهایی را تنظیم می کند که برنامه شما را شناسایی می کند و مجوزهایی را که از کاربر خواسته می شود به برنامه شما اعطا کند، تعریف می کند.
- اگر از کتابخانه سرویس گیرنده Google برای احراز هویت و مجوز OAuth 2.0 استفاده می کنید، شیئی را ایجاد و پیکربندی می کنید که این پارامترها را تعریف می کند.
- اگر مستقیماً با نقطه پایانی Google OAuth 2.0 تماس بگیرید، یک URL ایجاد میکنید و پارامترها را روی آن URL تنظیم میکنید.
برگه های زیر پارامترهای مجوز پشتیبانی شده را برای برنامه های وب سرور تعریف می کنند. مثالهای خاص زبان همچنین نحوه استفاده از کتابخانه مشتری یا کتابخانه مجوز را برای پیکربندی شیای که آن پارامترها را تنظیم میکند، نشان میدهد.
سرور مجوز Google از پارامترهای رشته پرس و جو زیر برای برنامه های وب سرور پشتیبانی می کند:
مولفه های | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id | ضروری شناسه مشتری برای برنامه شما. می توانید این مقدار را در API ConsoleCredentials pageپیدا کنید. | ||||||||||||||||||
redirect_uri | ضروری تعیین می کند که سرور API کاربر را پس از تکمیل جریان مجوز توسط کاربر به کجا هدایت می کند. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در API ConsoleCredentials pageمشتری خود پیکربندی کرده اید. اگر این مقدار با URI تغییر مسیر مجاز برای توجه داشته باشید که طرح | ||||||||||||||||||
response_type | ضروری تعیین می کند که آیا نقطه پایانی Google OAuth 2.0 یک کد مجوز را برمی گرداند یا خیر. مقدار پارامتر را برای | ||||||||||||||||||
scope | ضروری فهرستی از محدودههای محدود شده با فضا که منابعی را که برنامه شما میتواند از طرف کاربر به آنها دسترسی داشته باشد، شناسایی میکند. این مقادیر صفحه رضایتی را که Google به کاربر نشان می دهد، نشان می دهد. Scopes به برنامه شما امکان میدهد فقط درخواست دسترسی به منابع مورد نیاز خود را داشته باشد در حالی که کاربران را قادر میسازد تا میزان دسترسی را که به برنامه شما میدهند کنترل کنند. بنابراین، بین تعداد دامنه های درخواستی و احتمال کسب رضایت کاربر رابطه معکوس وجود دارد. YouTube Analytics API از حوزه های زیر استفاده می کند:
YouTube Reporting API از حوزه های زیر استفاده می کند:
سند OAuth 2.0 API Scopes فهرست کاملی از حوزه هایی را ارائه می دهد که ممکن است برای دسترسی به Google API از آنها استفاده کنید. توصیه میکنیم برنامه شما در صورت امکان، درخواست دسترسی به حوزههای مجوز در زمینه را داشته باشد. با درخواست دسترسی به دادههای کاربر در زمینه، از طریق مجوز افزایشی ، به کاربران کمک میکنید تا راحتتر بفهمند که چرا برنامه شما به دسترسی درخواستی نیاز دارد. | ||||||||||||||||||
access_type | توصیه شده نشان می دهد که آیا برنامه شما می تواند نشانه های دسترسی را در زمانی که کاربر در مرورگر حضور ندارد بازخوانی کند یا خیر. مقادیر پارامترهای معتبر اگر زمانی که کاربر در مرورگر حضور ندارد، برنامه شما نیاز به بازخوانی نشانه های دسترسی دارد، مقدار را روی | ||||||||||||||||||
state | توصیه شده هر مقدار رشته ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می کند، مشخص می کند. سرور مقدار دقیقی را که شما به عنوان یک جفت شما می توانید از این پارامتر برای اهداف مختلفی مانند هدایت کاربر به منبع صحیح در برنامه خود، ارسال nonces و کاهش جعل درخواست بین سایتی استفاده کنید. از آنجایی که | ||||||||||||||||||
include_granted_scopes | اختیاری برنامهها را قادر میسازد تا از مجوز افزایشی برای درخواست دسترسی به دامنههای اضافی در زمینه استفاده کنند. اگر مقدار این پارامتر را روی | ||||||||||||||||||
enable_granular_consent | اختیاری پیش فرض ها به وقتی Google مجوزهای گرانول را برای یک برنامه فعال می کند، این پارامتر دیگر هیچ تاثیری نخواهد داشت. | ||||||||||||||||||
login_hint | اختیاری اگر برنامه شما بداند که کدام کاربر در حال تلاش برای احراز هویت است، میتواند از این پارامتر برای ارائه راهنمایی به سرور احراز هویت Google استفاده کند. سرور از راهنمایی برای ساده سازی جریان ورود استفاده می کند یا با پر کردن فیلد ایمیل در فرم ورود به سیستم یا با انتخاب جلسه چند ورود مناسب. مقدار پارامتر را به آدرس ایمیل یا شناسه | ||||||||||||||||||
prompt | اختیاری فهرستی با فاصله محدود و حساس به حروف کوچک و بزرگ از درخواستها برای ارائه کاربر. اگر این پارامتر را مشخص نکنید، تنها اولین باری که پروژه شما درخواست دسترسی می کند، از کاربر خواسته می شود. برای اطلاعات بیشتر به درخواست رضایت مجدد مراجعه کنید. مقادیر ممکن عبارتند از:
|
کاربر را به سرور OAuth 2.0 Google هدایت کنید تا فرآیند احراز هویت و مجوز آغاز شود. به طور معمول، این زمانی اتفاق می افتد که برنامه شما ابتدا نیاز به دسترسی به داده های کاربر دارد. در مورد مجوز افزایشی ، این مرحله همچنین زمانی رخ می دهد که برنامه شما ابتدا نیاز به دسترسی به منابع اضافی دارد که هنوز مجوز دسترسی به آنها را ندارد.
HTTP/REST
Sample redirect to Google's authorization server
The sample URL below requests offline access
(access_type=offline
) to a scope that permits access to retrieve
the user's YouTube Analytics reports. It uses incremental authorization to
ensure that the new access token covers any scopes to which the user
previously granted the application access. The URL also sets values for the
required redirect_uri
, response_type
, and
client_id
parameters as well as for the state
parameter. The URL contains line breaks and spaces for readability.
https://accounts.google.com/o/oauth2/v2/auth?
scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
access_type=offline&
include_granted_scopes=true&
state=state_parameter_passthrough_value&
redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
response_type=code&
client_id=client_id
پس از ایجاد URL درخواست، کاربر را به آن هدایت کنید.
سرور OAuth 2.0 Google کاربر را احراز هویت می کند و از کاربر رضایت می گیرد تا برنامه شما به محدوده های درخواستی دسترسی پیدا کند. پاسخ با استفاده از URL تغییر مسیری که مشخص کرده اید به برنامه شما ارسال می شود.
در این مرحله، کاربر تصمیم می گیرد که آیا به اپلیکیشن شما دسترسی درخواستی را بدهد یا خیر. در این مرحله، گوگل یک پنجره رضایت را نمایش می دهد که نام برنامه شما و سرویس های Google API را نشان می دهد که درخواست اجازه دسترسی به آن ها را با اعتبار مجوز کاربر و خلاصه ای از محدوده های دسترسی که باید اعطا شود را نشان می دهد. سپس کاربر می تواند با اعطای دسترسی به یک یا چند حوزه درخواست شده توسط برنامه شما موافقت کند یا درخواست را رد کند.
برنامه شما در این مرحله نیازی به انجام هیچ کاری ندارد زیرا منتظر پاسخ سرور OAuth 2.0 Google است که نشان می دهد آیا دسترسی اعطا شده است یا خیر. این پاسخ در مرحله زیر توضیح داده شده است.
درخواستها به نقطه پایانی مجوز OAuth 2.0 Google ممکن است پیامهای خطای کاربر را بهجای جریانهای احراز هویت و مجوز مورد انتظار نمایش دهند. کدهای خطای رایج و راهکارهای پیشنهادی در زیر فهرست شدهاند.
admin_policy_enforced
حساب Google به دلیل خطمشیهای سرپرست Google Workspace نمیتواند یک یا چند محدوده درخواستی را تأیید کند. برای اطلاعات بیشتر در مورد اینکه چگونه یک سرپرست میتواند دسترسی به همه حوزهها یا محدودههای حساس و محدود را تا زمانی که صراحتاً به شناسه مشتری OAuth شما اعطا نشود، به مقاله راهنمای Google Workspace Admin مراجعه کنید.
disallowed_useragent
نقطه پایانی مجوز در داخل یک عامل کاربر تعبیهشده نمایش داده میشود که توسط خطمشیهای OAuth 2.0 Google مجاز نیست.
برنامهنویسان Android ممکن است هنگام باز کردن درخواستهای مجوز در android.webkit.WebView
با این پیام خطا مواجه شوند. توسعهدهندگان باید در عوض از کتابخانههای Android مانند Google Sign-In برای Android یا OpenID Foundation's AppAuth for Android استفاده کنند.
توسعه دهندگان وب ممکن است زمانی با این خطا مواجه شوند که یک برنامه Android یک پیوند وب کلی را در یک عامل کاربر تعبیه شده باز کند و کاربر به نقطه پایانی مجوز OAuth 2.0 Google از سایت شما هدایت شود. توسعهدهندگان باید اجازه دهند پیوندهای عمومی در کنترلکننده پیوند پیشفرض سیستمعامل، که شامل کنترلکنندههای پیوندهای برنامه Android یا برنامه مرورگر پیشفرض است، باز شوند. کتابخانه Android Custom Tabs نیز یک گزینه پشتیبانی شده است.
توسعه دهندگان iOS و macOS ممکن است هنگام باز کردن درخواست های مجوز در WKWebView
با این خطا مواجه شوند. توسعهدهندگان باید در عوض از کتابخانههای iOS مانند Google Sign-In برای iOS یا OpenID Foundations AppAuth برای iOS استفاده کنند.
زمانی که یک برنامه iOS یا macOS یک پیوند وب عمومی را در یک عامل کاربر تعبیه شده باز می کند و کاربر به نقطه پایانی مجوز OAuth 2.0 Google از سایت شما می رود، ممکن است توسعه دهندگان وب با این خطا مواجه شوند. توسعهدهندگان باید اجازه دهند پیوندهای عمومی در کنترلکننده پیوند پیشفرض سیستمعامل، که شامل کنترلکنندههای پیوندهای جهانی یا برنامه مرورگر پیشفرض است، باز شوند. کتابخانه SFSafariViewController
نیز یک گزینه پشتیبانی شده است.
org_internal
شناسه مشتری OAuth در درخواست بخشی از پروژه ای است که دسترسی به حساب های Google را در یک سازمان Google Cloud خاص محدود می کند. برای اطلاعات بیشتر در مورد این گزینه پیکربندی، بخش نوع کاربر را در مقاله راهنمای تنظیم صفحه رضایت OAuth خود ببینید.
invalid_client
راز مشتری OAuth نادرست است. پیکربندی سرویس گیرنده OAuth را مرور کنید، از جمله شناسه مشتری و راز استفاده شده برای این درخواست.
invalid_grant
هنگام بازخوانی یک نشانه دسترسی یا استفاده از مجوز افزایشی ، ممکن است نشانه منقضی شده باشد یا باطل شده باشد. مجدداً کاربر را احراز هویت کنید و برای دریافت توکن های جدید رضایت کاربر را بخواهید. اگر همچنان این خطا را مشاهده می کنید، مطمئن شوید که برنامه شما به درستی پیکربندی شده است و از نشانه ها و پارامترهای صحیح در درخواست خود استفاده می کنید. در غیر این صورت، حساب کاربری ممکن است حذف یا غیرفعال شده باشد.
redirect_uri_mismatch
redirect_uri
ارسال شده در درخواست مجوز با URI تغییر مسیر مجاز برای شناسه مشتری OAuth مطابقت ندارد. URIهای مجاز تغییر مسیر را در Google API Console Credentials pageمرور کنید.
پارامتر redirect_uri
ممکن است به جریان OAuth خارج از باند (OOB) اشاره داشته باشد که منسوخ شده است و دیگر پشتیبانی نمی شود. برای به روز رسانی ادغام خود به راهنمای مهاجرت مراجعه کنید.
invalid_request
مشکلی در درخواستی که دادید وجود داشت. این می تواند به دلایل مختلفی باشد:
- درخواست به درستی قالب بندی نشده بود
- درخواست فاقد پارامترهای لازم بود
- این درخواست از روش مجوزی استفاده میکند که Google از آن پشتیبانی نمیکند. بررسی کنید که ادغام OAuth شما از یک روش ادغام توصیه شده استفاده می کند
سرور OAuth 2.0 با استفاده از URL مشخص شده در درخواست به درخواست دسترسی برنامه شما پاسخ می دهد.
اگر کاربر درخواست دسترسی را تأیید کند، پاسخ حاوی یک کد مجوز است. اگر کاربر درخواست را تایید نکند، پاسخ حاوی یک پیام خطا است. کد مجوز یا پیغام خطایی که به وب سرور بازگردانده می شود، مانند شکل زیر در رشته کوئری ظاهر می شود:
یک پاسخ خطا:
https://oauth2.example.com/auth?error=access_denied
پاسخ کد مجوز:
https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7
میتوانید این جریان را با کلیک بر روی نشانی اینترنتی نمونه زیر آزمایش کنید، که دسترسی فقط خواندنی را برای مشاهده فراداده فایلها در Google Drive شما درخواست میکند:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& access_type=offline& include_granted_scopes=true& state=state_parameter_passthrough_value& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& response_type=code& client_id=client_id
پس از تکمیل جریان OAuth 2.0، باید به http://localhost/oauth2callback
هدایت شوید، که احتمالاً خطای 404 NOT FOUND
را ایجاد می کند، مگر اینکه دستگاه محلی شما فایلی را در آن آدرس ارائه کند. مرحله بعدی جزئیات بیشتری را در مورد اطلاعات بازگردانده شده در URI هنگامی که کاربر به برنامه شما هدایت می شود ارائه می دهد.
پس از اینکه وب سرور کد مجوز را دریافت کرد، می تواند کد مجوز را با یک نشانه دسترسی مبادله کند.
هنگام تعویض کد مجوز برای یک نشانه دسترسی، ممکن است به جای پاسخ مورد انتظار با خطای زیر مواجه شوید. کدهای خطای رایج و راهکارهای پیشنهادی در زیر فهرست شدهاند.
invalid_grant
کد مجوز ارائه شده نامعتبر است یا در قالب اشتباه است. با راهاندازی مجدد فرآیند OAuth، یک کد جدید درخواست کنید تا دوباره رضایت کاربر را بخواهد.
مثال زیر یک شی با فرمت JSON را چاپ میکند که دادههای بازدیدها را برای کانال یوتیوب کاربر احراز هویت شده نشان میدهد پس از اینکه کاربر به برنامه اجازه بازیابی گزارشهای YouTube Analytics را داد.
Google قوانین اعتبارسنجی زیر را برای تغییر مسیر URI ها اعمال می کند تا به توسعه دهندگان کمک کند برنامه های خود را ایمن نگه دارند. URI های تغییر مسیر شما باید از این قوانین پیروی کنند. RFC 3986 بخش 3 را برای تعریف دامنه، میزبان، مسیر، پرس و جو، طرح و اطلاعات کاربری که در زیر ذکر شده است، ببینید.
قوانین اعتبارسنجی | |
---|---|
طرح | URIهای تغییر مسیر باید از طرح HTTPS استفاده کنند، نه HTTP ساده. URI های لوکال هاست (از جمله URI های IP آدرس لوکال هاست) از این قانون مستثنی هستند. |
میزبان | هاست ها نمی توانند آدرس IP خام باشند. آدرس های IP Localhost از این قانون مستثنی هستند. |
دامنه | “googleusercontent.com” باشد.goo.gl ) باشند، مگر اینکه برنامه مالک دامنه باشد. علاوه بر این، اگر برنامهای که دارای دامنه کوتاهکننده است، تغییر مسیر به آن دامنه را انتخاب کند، آن URI تغییر مسیر یا باید حاوی “/google-callback/” در مسیر خود باشد یا به “/google-callback” ختم شود. |
اطلاعات کاربر | URI های تغییر مسیر نمی توانند شامل زیرمجموعه اطلاعات کاربر باشند. |
مسیر | URI های تغییر مسیر نمی توانند شامل پیمایش مسیر (همچنین به نام بک ترک دایرکتوری) باشند که با |
پرس و جو | URI های تغییر مسیر نمی توانند حاوی تغییر مسیرهای باز باشند. |
قطعه | URI های تغییر مسیر نمی توانند شامل جزء قطعه باشند. |
شخصیت ها | URI های تغییر مسیر نمی توانند شامل کاراکترهای خاصی باشند از جمله:
|
در پروتکل OAuth 2.0، برنامه شما مجوز دسترسی به منابع را درخواست میکند که با محدودهها مشخص میشوند. درخواست مجوز برای منابع در زمانی که به آنها نیاز دارید بهترین روش تجربه کاربر در نظر گرفته می شود. برای فعال کردن این عمل، سرور مجوز Google از مجوز افزایشی پشتیبانی می کند. این ویژگی به شما امکان میدهد دامنهها را در صورت نیاز درخواست کنید و اگر کاربر مجوز دامنه جدید را صادر کند، یک کد مجوز را برمیگرداند که ممکن است با توکنی مبادله شود که شامل تمام محدودههایی است که کاربر به پروژه اعطا کرده است.
به عنوان مثال، فرض کنید برنامهای گزارشهای YouTube Analytics را بازیابی میکند، برخی از آنها گزارشهای پولی هستند که نیاز به دسترسی به دامنه اضافی دارند که برای گزارشهای دیگر مورد نیاز نیست. در این مورد، در زمان ورود به سیستم، برنامه فقط ممکن است درخواست دسترسی به حوزه https://www.googleapis.com/auth/yt-analytics.readonly
کند. با این حال، اگر کاربر سعی در بازیابی گزارش پولی داشته باشد، برنامه همچنین میتواند درخواست دسترسی به حوزه https://www.googleapis.com/auth/yt-analytics-monetary.readonly
را نیز بکند.
برای اجرای مجوز افزایشی، جریان عادی درخواست یک نشانه دسترسی را تکمیل میکنید، اما مطمئن شوید که درخواست مجوز شامل محدودههایی است که قبلاً اعطا شده است. این رویکرد به برنامه شما اجازه می دهد تا از مدیریت توکن های دسترسی چندگانه اجتناب کند.
قوانین زیر برای یک نشانه دسترسی به دست آمده از مجوز افزایشی اعمال می شود:
- توکن را می توان برای دسترسی به منابع مربوط به هر یک از حوزه های موجود در مجوز جدید ترکیبی استفاده کرد.
- هنگامی که از نشانه بازخوانی برای مجوز ترکیبی برای به دست آوردن یک نشانه دسترسی استفاده می کنید، نشانه دسترسی نشان دهنده مجوز ترکیبی است و می تواند برای هر یک از مقادیر
scope
موجود در پاسخ استفاده شود. - مجوز ترکیبی شامل تمام حوزه هایی است که کاربر به پروژه API اعطا کرده است، حتی اگر کمک هزینه ها از مشتریان مختلف درخواست شده باشد. به عنوان مثال، اگر کاربری با استفاده از کلاینت دسکتاپ یک برنامه به یک محدوده دسترسی داشته باشد و سپس از طریق یک کلاینت تلفن همراه به همان برنامه دسترسی داشته باشد، مجوز ترکیبی شامل هر دو حوزه می شود.
- اگر رمزی را که نشان دهنده یک مجوز ترکیبی است لغو کنید، دسترسی به تمام حوزه های آن مجوز از طرف کاربر مرتبط به طور همزمان لغو می شود.
نمونه کدهای خاص زبان در مرحله 1: تنظیم پارامترهای مجوز و نمونه URL تغییر مسیر HTTP/REST در مرحله 2: هدایت مجدد به سرور OAuth 2.0 Google همگی از مجوز افزایشی استفاده می کنند. نمونههای کد زیر نیز کدی را نشان میدهند که برای استفاده از مجوز افزایشی باید اضافه کنید.
Refreshing an access token (offline access)
Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.
- If you use a Google API Client Library, the client object refreshes the access token as needed as long as you configure that object for offline access.
- If you are not using a client library, you need to set the
access_type
HTTP query parameter tooffline
when redirecting the user to Google's OAuth 2.0 server. In that case, Google's authorization server returns a refresh token when you exchange an authorization code for an access token. Then, if the access token expires (or at any other time), you can use a refresh token to obtain a new access token.
Requesting offline access is a requirement for any application that needs to access a Google
API when the user is not present. For example, an app that performs backup services or
executes actions at predetermined times needs to be able to refresh its access token when the
user is not present. The default style of access is called online
.
Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process. Refresh tokens are not typically used in client-side (JavaScript) web applications.
PHP
If your application needs offline access to a Google API, set the API client's access type to
offline
:
$client->setAccessType("offline");
پس از اعطای دسترسی آفلاین به دامنه های درخواستی توسط کاربر، زمانی که کاربر آفلاین است، می توانید به استفاده از سرویس گیرنده API برای دسترسی به API های Google از طرف او ادامه دهید. شی کلاینت در صورت نیاز، نشانه دسترسی را بازخوانی می کند.
در برخی موارد ممکن است کاربر بخواهد دسترسی داده شده به یک برنامه را لغو کند. کاربر میتواند با مراجعه به تنظیمات حساب ، دسترسی را لغو کند. برای اطلاعات بیشتر به بخش حذف دسترسی به سایت یا برنامه از سایت ها و برنامه های شخص ثالث با دسترسی به سند پشتیبانی حساب خود مراجعه کنید.
همچنین این امکان وجود دارد که یک برنامه به صورت برنامه نویسی دسترسی داده شده به آن را لغو کند. لغو برنامهای در مواردی مهم است که کاربر اشتراک خود را لغو میکند، برنامهای را حذف میکند یا منابع API مورد نیاز یک برنامه به طور قابل توجهی تغییر کرده است. به عبارت دیگر، بخشی از فرآیند حذف می تواند شامل یک درخواست API برای اطمینان از حذف مجوزهایی باشد که قبلاً به برنامه اعطا شده است.