کتابخانه جاوا اسکریپت مجوز Google 3P برای وب سایت ها - مرجع API

این مرجع API کتابخانه جاوا اسکریپت مجوز Google 3P را توصیف می‌کند که می‌توانید از آن برای بارگیری کدهای مجوز یا دسترسی به نشانه‌های Google استفاده کنید.

روش: google.accounts.oauth2.initCodeClient

متد initCodeClient یک سرویس گیرنده کد را با تنظیمات موجود در پارامتر مقداردهی اولیه کرده و برمی گرداند. 

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

نوع داده: CodeClientConfig

جدول زیر ویژگی های نوع داده CodeClientConfig را فهرست می کند.

خواص
client_id مورد نیاز. شناسه مشتری برای برنامه شما. می توانید این مقدار را در کنسول API پیدا کنید.
scope مورد نیاز. فهرستی از محدوده‌های محدود شده با فضا که منابعی را که برنامه شما می‌تواند از طرف کاربر به آنها دسترسی داشته باشد، شناسایی می‌کند. این مقادیر صفحه رضایتی را که Google به کاربر نشان می دهد، نشان می دهد.
include_granted_scopes اختیاری، پیش‌فرض روی true است. برنامه‌ها را قادر می‌سازد تا از مجوز افزایشی برای درخواست دسترسی به دامنه‌های اضافی در زمینه استفاده کنند. اگر مقدار این پارامتر را روی false تنظیم کنید و درخواست مجوز اعطا شود، رمز دسترسی جدید فقط دامنه‌هایی را پوشش می‌دهد که scope درخواست شده در این CodeClientConfig .
redirect_uri برای تغییر مسیر UX مورد نیاز است. تعیین می کند که سرور API کاربر را پس از تکمیل جریان مجوز توسط کاربر به کجا هدایت می کند. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در کنسول API پیکربندی کرده‌اید و باید با قوانین اعتبارسنجی Redirect URI ما مطابقت داشته باشد. ویژگی توسط UX بازشو نادیده گرفته می شود.
callback برای UX پاپ آپ مورد نیاز است. تابع جاوا اسکریپت که پاسخ کد برگشتی را مدیریت می کند. ویژگی توسط تغییر مسیر UX نادیده گرفته می شود.
state اختیاری. برای تغییر مسیر UX توصیه می شود. هر مقدار رشته ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می کند، مشخص می کند.
enable_granular_consent اختیاری، پیش‌فرض روی true است. اگر روی false تنظیم شود، مجوزهای دقیق‌تر حساب Google برای شناسه‌های سرویس گیرنده OAuth ایجاد شده قبل از سال ۲۰۱۹ غیرفعال می‌شود. اگر هر دو enable_granular_consent و enable_serial_consent تنظیم شوند، فقط مقدار enable_granular_consent اعمال می‌شود و مقدار enable_serial_consent نادیده گرفته می‌شود.

هیچ تاثیری برای شناسه های سرویس گیرنده OAuth جدیدتر وجود ندارد، زیرا مجوزهای دقیق تری همیشه برای آنها فعال است.
enable_serial_consent منسوخ شده است، به جای آن باید از enable_granular_consent استفاده کنید. این همان اثر enable_granular_consent را دارد. برنامه‌های موجود که از enable_serial_consent استفاده می‌کنند می‌توانند به این کار ادامه دهند، اما شما تشویق می‌شوید کد خود را به‌روزرسانی کنید تا از enable_granular_consent در به‌روزرسانی برنامه بعدی خود استفاده کنید.
login_hint اختیاری. اگر برنامه شما بداند که کدام کاربر باید درخواست را تأیید کند، می‌تواند از این ویژگی برای ارائه راهنمایی ورود به Google استفاده کند. در صورت موفقیت آمیز بودن، انتخاب حساب حذف می شود. مقدار فیلد فرعی نشانی ایمیل یا شناسه برای کاربر هدف. برای اطلاعات بیشتر، به قسمت login_hint در اسناد OpenID Connect مراجعه کنید.
hd اختیاری. اگر برنامه شما دامنه Workspace را که کاربر به آن تعلق دارد می داند، از آن برای ارائه راهنمایی به Google استفاده کنید. در صورت موفقیت آمیز بودن، حساب های کاربری به دامنه ارائه شده محدود می شوند یا از قبل برای آن انتخاب می شوند. برای اطلاعات بیشتر، فیلد hd را در اسناد OpenID Connect ببینید.
ux_mode اختیاری. حالت UX برای استفاده برای جریان مجوز. به طور پیش فرض، جریان رضایت را در یک پنجره باز می کند. مقادیر معتبر popup و redirect هستند.
select_account اختیاری، پیش‌فرض «نادرست» است. مقدار بولی برای درخواست از کاربر برای انتخاب یک حساب.
error_callback اختیاری. تابع جاوا اسکریپت که برخی از خطاهای غیر OAuth را مدیریت می کند، مانند پنجره بازشو باز نشد. یا قبل از بازگشت پاسخ OAuth بسته شود.

فیلد «نوع» پارامتر ورودی دلیل دقیق را نشان می دهد.
  • popup_failed_to_open پنجره بازشو باز نشد.
  • popup_closed پنجره بازشو قبل از بازگشت یک پاسخ OAuth بسته می شود.
  • مکان نگهدار ناشناخته برای سایر خطاها.

نوع داده: CodeClient

کلاس فقط یک متد عمومی requestCode دارد که جریان OAuth 2.0 Code UX را شروع می کند. 

interface CodeClient {
  requestCode(): void;
}

نوع داده: CodeResponse

یک شی جاوا اسکریپت CodeResponse به روش callback شما در UX بازشو ارسال می شود. در تغییر مسیر UX، CodeResponse به عنوان پارامترهای URL ارسال می شود.

جدول زیر ویژگی های نوع داده CodeResponse را فهرست می کند.

خواص
code کد مجوز یک پاسخ توکن موفق.
scope فهرستی از محدوده‌ها با فاصله محدود که توسط کاربر تأیید شده است.
state مقدار رشته ای که برنامه شما برای حفظ وضعیت بین درخواست مجوز و پاسخ استفاده می کند.
error یک کد خطای ASCII.
error_description متن ASCII قابل خواندن توسط انسان اطلاعات اضافی را ارائه می دهد که برای کمک به توسعه دهنده مشتری در درک خطای رخ داده استفاده می شود.
error_uri یک URI که یک صفحه وب قابل خواندن توسط انسان را با اطلاعات مربوط به خطا شناسایی می کند و برای ارائه اطلاعات اضافی درباره خطا به توسعه دهنده سرویس گیرنده استفاده می شود.

روش: google.accounts.oauth2.initTokenClient

متد initTokenClient یک کلاینت توکن را با تنظیمات موجود در پارامتر، مقداردهی اولیه کرده و برمی گرداند. 

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

نوع داده: TokenClientConfig

جدول زیر ویژگی های نوع داده TokenClientConfig را فهرست می کند.

خواص
client_id مورد نیاز. شناسه مشتری برای برنامه شما. می توانید این مقدار را در کنسول API پیدا کنید.
callback مورد نیاز. تابع جاوا اسکریپت که پاسخ توکن برگشتی را کنترل می کند.
scope مورد نیاز. فهرستی از محدوده‌های محدود شده با فضا که منابعی را که برنامه شما می‌تواند از طرف کاربر به آنها دسترسی داشته باشد، شناسایی می‌کند. این مقادیر صفحه رضایتی را که Google به کاربر نشان می دهد، نشان می دهد.
include_granted_scopes اختیاری، پیش‌فرض روی true است. برنامه‌ها را قادر می‌سازد تا از مجوز افزایشی برای درخواست دسترسی به دامنه‌های اضافی در زمینه استفاده کنند. اگر مقدار این پارامتر را روی false تنظیم کنید و درخواست مجوز اعطا شود، رمز دسترسی جدید فقط دامنه‌هایی را پوشش می‌دهد که scope درخواست شده در این TokenClientConfig .
prompt اختیاری، پیش‌فرض «select_account» است. فهرستی با فاصله محدود و حساس به حروف کوچک و بزرگ از درخواست‌ها برای ارائه کاربر. مقادیر ممکن عبارتند از:
  • رشته خالی فقط اولین باری که برنامه شما درخواست دسترسی کند از کاربر خواسته می شود. نمی توان با مقادیر دیگر مشخص کرد.
  • "هیچ" هیچ صفحه تایید یا رضایتی را نمایش ندهید. نباید با مقادیر دیگر مشخص شود.
  • "رضایت" از کاربر درخواست رضایت کنید.
  • 'select_account' از کاربر بخواهد یک حساب را انتخاب کند.
enable_granular_consent اختیاری، پیش‌فرض روی true است. اگر روی false تنظیم شود، مجوزهای دقیق‌تر حساب Google برای شناسه‌های سرویس گیرنده OAuth ایجاد شده قبل از سال ۲۰۱۹ غیرفعال می‌شود. اگر هر دو enable_granular_consent و enable_serial_consent تنظیم شوند، فقط مقدار enable_granular_consent اعمال می‌شود و مقدار enable_serial_consent نادیده گرفته می‌شود.

هیچ تاثیری برای شناسه های سرویس گیرنده OAuth جدیدتر وجود ندارد، زیرا مجوزهای دقیق تری همیشه برای آنها فعال است.
enable_serial_consent منسوخ شده است، به جای آن باید از enable_granular_consent استفاده کنید. این همان اثر enable_granular_consent را دارد. برنامه‌های موجود که از enable_serial_consent استفاده می‌کنند می‌توانند به این کار ادامه دهند، اما شما تشویق می‌شوید کد خود را به‌روزرسانی کنید تا از enable_granular_consent در به‌روزرسانی برنامه بعدی خود استفاده کنید.
login_hint اختیاری. اگر برنامه شما بداند که کدام کاربر باید درخواست را تأیید کند، می‌تواند از این ویژگی برای ارائه راهنمایی ورود به Google استفاده کند. در صورت موفقیت آمیز بودن، انتخاب حساب حذف می شود. مقدار فیلد فرعی نشانی ایمیل یا شناسه برای کاربر هدف. برای اطلاعات بیشتر، به قسمت login_hint در اسناد OpenID Connect مراجعه کنید.
hd اختیاری. اگر برنامه شما دامنه Workspace را که کاربر به آن تعلق دارد می داند، از آن برای ارائه راهنمایی به Google استفاده کنید. در صورت موفقیت آمیز بودن، حساب های کاربری به دامنه ارائه شده محدود می شوند یا از قبل برای آن انتخاب می شوند. برای اطلاعات بیشتر، فیلد hd را در اسناد OpenID Connect ببینید.
state اختیاری. توصیه نمی شود. هر مقدار رشته ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می کند، مشخص می کند.
error_callback اختیاری. تابع جاوا اسکریپت که برخی از خطاهای غیر OAuth را مدیریت می کند، مانند پنجره بازشو باز نشد. یا قبل از بازگشت پاسخ OAuth بسته شود.

فیلد «نوع» پارامتر ورودی دلیل دقیق را نشان می دهد.
  • popup_failed_to_open پنجره بازشو باز نشد.
  • popup_closed پنجره بازشو قبل از بازگشت یک پاسخ OAuth بسته می شود.
  • مکان نگهدار ناشناخته برای سایر خطاها.

نوع داده: TokenClient

کلاس فقط یک متد عمومی requestAccessToken دارد که جریان OAuth 2.0 Token UX را شروع می کند. 

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
استدلال ها
overrideConfig OverridableTokenClientConfig اختیاری. تنظیماتی که در این روش باید لغو شوند.

نوع داده: OverridableTokenClientConfig

جدول زیر ویژگی های نوع داده OverridableTokenClientConfig را فهرست می کند.

خواص
scope اختیاری. فهرستی از محدوده‌های محدود شده با فضا که منابعی را که برنامه شما می‌تواند از طرف کاربر به آنها دسترسی داشته باشد، شناسایی می‌کند. این مقادیر صفحه رضایتی را که Google به کاربر نشان می دهد، نشان می دهد.
include_granted_scopes اختیاری، پیش‌فرض روی true است. برنامه‌ها را قادر می‌سازد تا از مجوز افزایشی برای درخواست دسترسی به دامنه‌های اضافی در زمینه استفاده کنند. اگر مقدار این پارامتر را روی false تنظیم کنید و درخواست مجوز اعطا شود، رمز دسترسی جدید فقط دامنه‌هایی را پوشش می‌دهد که scope درخواست شده در این OverridableTokenClientConfig .
prompt اختیاری. فهرستی با فاصله محدود و حساس به حروف کوچک و بزرگ از درخواست‌ها برای ارائه کاربر.
enable_granular_consent اختیاری، پیش‌فرض روی true است. اگر روی false تنظیم شود، مجوزهای دقیق‌تر حساب Google برای شناسه‌های سرویس گیرنده OAuth ایجاد شده قبل از سال 2019 غیرفعال می‌شود. اگر هر دو enable_granular_consent و enable_serial_consent تنظیم شوند، فقط مقدار enable_granular_consent اعمال می‌شود و مقدار enable_serial_consent نادیده گرفته می‌شود.

هیچ تاثیری برای شناسه های سرویس گیرنده OAuth جدیدتر وجود ندارد، زیرا مجوزهای دقیق تری همیشه برای آنها فعال است.
enable_serial_consent منسوخ شده است، به جای آن باید از enable_granular_consent استفاده کنید. این همان اثر enable_granular_consent را دارد. برنامه‌های موجود که از enable_serial_consent استفاده می‌کنند می‌توانند به این کار ادامه دهند، اما شما تشویق می‌شوید کد خود را به‌روزرسانی کنید تا از enable_granular_consent در به‌روزرسانی برنامه بعدی خود استفاده کنید.
login_hint اختیاری. اگر برنامه شما بداند که کدام کاربر باید درخواست را تأیید کند، می‌تواند از این ویژگی برای ارائه راهنمایی ورود به Google استفاده کند. در صورت موفقیت آمیز بودن، انتخاب حساب حذف می شود. مقدار فیلد فرعی نشانی ایمیل یا شناسه برای کاربر هدف. برای اطلاعات بیشتر، به قسمت login_hint در اسناد OpenID Connect مراجعه کنید.
state اختیاری. توصیه نمی شود. هر مقدار رشته ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می کند، مشخص می کند.

نوع داده: TokenResponse

یک شی جاوا اسکریپت TokenResponse به روش پاسخ به تماس شما در UX بازشو ارسال می شود.

جدول زیر ویژگی های نوع داده TokenResponse را فهرست می کند.

خواص
access_token نشانه دسترسی یک پاسخ توکن موفق.
expires_in طول عمر رمز دسترسی بر حسب ثانیه.
hd دامنه میزبانی که کاربر وارد شده به آن تعلق دارد.
prompt مقدار درخواستی که از لیست احتمالی مقادیر مشخص شده توسط TokenClientConfig یا OverridableTokenClientConfig استفاده شده است.
token_type نوع توکن صادر شده
scope فهرستی از محدوده‌ها با فاصله محدود که توسط کاربر تأیید شده است.
state مقدار رشته ای که برنامه شما برای حفظ وضعیت بین درخواست مجوز و پاسخ استفاده می کند.
error یک کد خطای ASCII.
error_description متن ASCII قابل خواندن توسط انسان اطلاعات اضافی را ارائه می دهد که برای کمک به توسعه دهنده مشتری در درک خطای رخ داده استفاده می شود.
error_uri یک URI که یک صفحه وب قابل خواندن توسط انسان را با اطلاعات مربوط به خطا شناسایی می کند و برای ارائه اطلاعات اضافی درباره خطا به توسعه دهنده سرویس گیرنده استفاده می شود.

روش: google.accounts.oauth2.hasGrantedAllScopes

بررسی می کند که آیا کاربر تمام محدوده یا دامنه های مشخص شده را اعطا کرده است یا خیر. 

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
استدلال ها
tokenResponse TokenResponse مورد نیاز. یک شی TokenResponse .
firstScope رشته مورد نیاز. محدوده برای بررسی.
restScopes رشته[] اختیاری. حوزه های دیگر برای بررسی
برمی گرداند
بولی درست است اگر همه دامنه ها اعطا شود.

روش: google.accounts.oauth2.hasGrantedAnyScope

بررسی می کند که آیا کاربر هر یک از محدوده یا محدوده های مشخص شده را اعطا کرده است یا خیر. 

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
استدلال ها
tokenResponse TokenResponse مورد نیاز. یک شی TokenResponse .
firstScope رشته مورد نیاز. محدوده برای بررسی.
restScopes رشته[] اختیاری. حوزه های دیگر برای بررسی
برمی گرداند
بولی اگر هر یک از دامنه ها اعطا شود درست است.

روش: google.accounts.oauth2.revoke

روش revoke تمام دامنه هایی را که کاربر به برنامه داده است باطل می کند. یک نشانه دسترسی معتبر برای لغو مجوز لازم است. 

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
استدلال ها
accessToken رشته مورد نیاز. یک نشانه دسترسی معتبر
callback تابع اختیاری. کنترل کننده RevocationResponse .

نوع داده: RevocationResponse

یک شی جاوا اسکریپت RevocationResponse به روش پاسخ به تماس شما ارسال می شود.

جدول زیر ویژگی های نوع داده RevocationResponse را فهرست می کند.

خواص
successful بولی. true در مورد موفق، false در شکست.
error رشته در مورد موفقیت تعریف نشده است. یک کد خطای ASCII. این شامل، اما نه محدود به کدهای خطای استاندارد OAuth 2.0 است . خطاهای رایج برای روش revoke :
  • invalid_token - رمز قبلا منقضی شده یا قبل از فراخوانی روش revoke لغو شده است. در بیشتر موارد، می‌توانید در نظر بگیرید که کمک مالی مرتبط با accessToken لغو شده است.
  • invalid_request - توکن قابل فسخ نیست. باید مطمئن شوید که accessToken یک اعتبارنامه معتبر Google OAuth 2.0 است.
error_description رشته در مورد موفقیت تعریف نشده است. متن ASCII قابل خواندن توسط انسان اطلاعات بیشتری در مورد ویژگی error ارائه می دهد. توسعه دهندگان می توانند از این برای درک بهتر خطای رخ داده استفاده کنند. رشته error_description فقط به زبان انگلیسی است. برای خطاهای رایج فهرست شده به error error_description مربوطه:
  • invalid_token - توکن منقضی یا باطل شده است.
  • invalid_request - توکن قابل فسخ نیست.