یک کلید API یک رشته منحصر به فرد است که برای هدایت درخواست‌ها به پروژه Firebase شما هنگام تعامل با Firebase و سرویس‌های Google استفاده می‌شود. این صفحه اطلاعات اولیه در مورد کلیدهای API و همچنین بهترین روش‌ها برای استفاده و مدیریت کلیدهای API با برنامه‌های Firebase را توضیح می‌دهد.
اطلاعات کلی در مورد کلیدهای API و Firebase
کلیدهای API برای Firebase با کلیدهای API معمولی متفاوت هستند
برخلاف نحوه استفاده از کلیدهای API، کلیدهای API برای سرویس‌های Firebase برای کنترل دسترسی به منابع پشتیبان استفاده نمی‌شوند . که فقط با قوانین امنیتی Firebase (برای کنترل اینکه کدام کاربران می توانند به منابع دسترسی داشته باشند) و App Check (برای کنترل برنامه هایی که می توانند به منابع دسترسی داشته باشند) قابل انجام است.
معمولاً باید به دقت از کلیدهای API محافظت کنید (مثلاً با استفاده از سرویس خزانه یا تنظیم کلیدها به عنوان متغیرهای محیطی). با این حال، کلیدهای API برای سرویس‌های Firebase برای گنجاندن در کد یا فایل‌های پیکربندی تأییدشده مناسب هستند.
اگرچه کلیدهای API برای سرویس‌های Firebase برای گنجاندن در کد ایمن هستند، چند مورد خاص وجود دارد که باید محدودیت‌هایی را برای کلید API خود اعمال کنید. برای مثال، اگر از Firebase ML، Firebase Authentication با روش ورود به سیستم ایمیل/گذرواژه یا Google Cloud API قابل پرداخت استفاده می‌کنید. در ادامه این صفحه درباره این موارد بیشتر بدانید.
ایجاد کلیدهای API
یک پروژه Firebase می‌تواند کلیدهای API زیادی داشته باشد، اما هر کلید API فقط می‌تواند با یک پروژه Firebase مرتبط باشد.
وقتی یکی از کارهای زیر را انجام می دهید، Firebase به طور خودکار کلیدهای API را برای پروژه شما ایجاد می کند:
- یک پروژه Firebase ایجاد کنید >
Browser keyبه طور خودکار ایجاد شد - یک برنامه Firebase Apple ایجاد کنید >
iOS keyبه طور خودکار ایجاد می شود - یک برنامه Android Firebase ایجاد کنید >
Android keyبه طور خودکار ایجاد شود
همچنین می توانید کلیدهای API خود را در Google Cloud Console ایجاد کنید، به عنوان مثال برای توسعه یا اشکال زدایی . در مورد زمانی که ممکن است بعداً در این صفحه توصیه شود، بیشتر بیاموزید.
پیدا کردن کلیدهای API
می‌توانید تمام کلیدهای API پروژه خود را در APIs & Services > پنل اعتبارنامه‌ها در Google Cloud Console مشاهده و مدیریت کنید.
همچنین در مکان‌های زیر می‌توانید بیابید کدام کلید API به طور خودکار با برنامه Firebase مطابقت دارد . به طور پیش‌فرض، همه برنامه‌های Firebase پروژه شما برای یک پلتفرم (Apple vs Android vs Web) از یک کلید API استفاده می‌کنند.
Firebase Apple Apps - کلید API منطبق خودکار برنامه را در فایل پیکربندی Firebase،
GoogleService-Info.plist API_KEYپیدا کنید.Firebase Android Apps — کلید API منطبق خودکار یک برنامه را در فایل پیکربندی Firebase،
google-services.json current_keyپیدا کنید.برنامه های وب Firebase - کلید API مطابق خودکار یک برنامه را در شی پیکربندی Firebase، در قسمت
apiKeyکنید.
استفاده از کلید API
کلیدهای API برای شناسایی پروژه Firebase شما هنگام تعامل با سرویس‌های Firebase/Google استفاده می‌شوند. به طور خاص، از آنها برای مرتبط کردن درخواست های API با پروژه شما برای سهمیه و صورتحساب استفاده می شود. آنها همچنین برای دسترسی به داده های عمومی مفید هستند.
به عنوان مثال، شما می توانید به صراحت از یک کلید API با ارسال مقدار آن به یک فراخوانی REST API به عنوان پارامتر پرس و جو استفاده کنید. این مثال نشان می‌دهد که چگونه می‌توانید به API کوتاه‌کننده پیوند پیوندهای پویا درخواست بدهید:
POST https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY
هنگامی که برنامه شما با یک API Firebase تماس می گیرد، برنامه شما به طور خودکار در فایل پیکربندی Firebase یا شی کلید API پروژه شما جستجو می کند. با این حال، می توانید کلیدهای API خود را با استفاده از مکانیزم متفاوتی از جمله متغیرهای محیطی تنظیم کنید.
اعمال محدودیت برای کلیدهای API (توصیه می شود)
اگرچه لازم نیست یک کلید API برای سرویس های Firebase به عنوان یک راز تلقی شود، موارد خاصی وجود دارد (به زیر مراجعه کنید) که در آنها ممکن است بخواهید اقدامات بیشتری برای محافظت از پروژه خود در برابر سوء استفاده از کلید API انجام دهید.
اگر از احراز هویت مبتنی بر رمز عبور استفاده می کنید، سهمیه را تشدید کنید
اگر از احراز هویت Firebase مبتنی بر رمز عبور استفاده می‌کنید و شخصی کلید API شما را در دست می‌گیرد، تا زمانی که این داده‌ها توسط قوانین امنیتی Firebase محافظت می‌شوند، نمی‌توانند به هیچ یک از پایگاه داده پروژه Firebase یا داده‌های Cloud Storage شما دسترسی داشته باشند. با این حال، آنها می توانند از کلید API شما برای دسترسی به نقاط پایانی احراز هویت Firebase و درخواست احراز هویت در برابر پروژه شما استفاده کنند.
برای کاهش احتمال سوء استفاده شخصی از یک کلید API برای حمله brute force، می‌توانید سهمیه پیش‌فرض نقاط انتهایی identitytoolkit.googleapis.com را محدود کنید تا انتظارات ترافیک عادی برنامه شما را منعکس کند. توجه داشته باشید که اگر این سهمیه را تشدید کنید و برنامه شما به طور ناگهانی کاربرانی پیدا کند، ممکن است تا زمانی که سهمیه را افزایش ندهید، با خطاهای ورود مواجه شوید. می‌توانید سهمیه‌های API پروژه خود را در Google Cloud Console تغییر دهید.
از کلیدهای API جداگانه و محدود برای انواع خاصی از APIها استفاده کنید
اگرچه کلیدهای API مورد استفاده برای سرویس‌های Firebase معمولاً نیازی به مخفی بودن ندارند، باید اقدامات احتیاطی بیشتری را در مورد کلیدهای API مورد استفاده برای دسترسی به APIهای Google Cloud که به صورت دستی فعال کرده‌اید، انجام دهید.
اگر از Google Cloud API (در هر پلتفرمی) استفاده می‌کنید که به‌طور خودکار توسط Firebase فعال نمی‌شود (یعنی خودتان آن را فعال کرده‌اید)، باید کلیدهای API محدود و مجزا برای استفاده با آن APIها ایجاد کنید. اگر API برای سرویس Google Cloud قابل پرداخت باشد، این امر به ویژه مهم است.
به عنوان مثال، اگر از API های Cloud Vision Firebase ML در iOS استفاده می کنید، باید کلیدهای API جداگانه ای ایجاد کنید که فقط برای دسترسی به API های Cloud Vision استفاده می کنید.
با استفاده از کلیدهای API مجزا و محدود برای APIهای غیر Firebase، می‌توانید در صورت لزوم کلیدها را بچرخانید یا جایگزین کنید و بدون ایجاد اختلال در استفاده از سرویس‌های Firebase ، محدودیت‌های اضافی به کلیدهای API اضافه کنید .
این دستورالعمل‌ها نحوه ایجاد یک کلید API مجزا و محدود برای یک API جعلی به نام Super Service API توضیح می‌دهند.
مرحله 1: کلیدهای API موجود خود را پیکربندی کنید تا دسترسی به Super Service API ممنوع شود
صفحه اعتبارنامه Google Cloud Console را باز کنید. وقتی از شما خواسته شد، پروژه خود را انتخاب کنید.
برای هر کلید API موجود در لیست، نمای ویرایش را باز کنید.
در بخش محدودیت‌های API ، Restrict key را انتخاب کنید، سپس همه APIهایی را که می‌خواهید کلید API به آنها دسترسی داشته باشد، به لیست اضافه کنید. اطمینان حاصل کنید که API را که برای آن یک کلید API جداگانه ایجاد می‌کنید (در این مثال،
Super Service API) درج نکنید.وقتی محدودیت‌های API کلید API را پیکربندی می‌کنید، به صراحت APIهایی را که کلید به آنها دسترسی دارد، اعلام می‌کنید. به‌طور پیش‌فرض، زمانی که در بخش محدودیت‌های API کلید Don't limited key انتخاب شده باشد، می‌توان از یک کلید API برای دسترسی به هر API که برای پروژه فعال است استفاده کرد.
اکنون، کلیدهای API موجود شما اجازه دسترسی به Super Service API را نمی‌دهند، اما هر کلید برای هر APIهایی که به فهرست محدودیت‌های API اضافه کرده‌اید به کار خود ادامه می‌دهد.
مرحله 2: یک کلید API جدید برای دسترسی به Super Service API ایجاد کنید و از آن استفاده کنید
به صفحه اعتبارنامه بازگردید . مطمئن شوید که پروژه Firebase شما هنوز انتخاب شده است.
روی ایجاد اعتبارنامه > کلید API کلیک کنید. کلید API جدید را یادداشت کنید، سپس روی Restrict key کلیک کنید.
در بخش محدودیت‌های API ، Restrict key را انتخاب کنید، سپس فقط
Super Service APIرا به لیست اضافه کنید.این کلید API جدید فقط به
Super Service APIدسترسی می دهد.برنامه و خدمات خود را برای استفاده از کلید API جدید پیکربندی کنید.
استفاده از کلیدهای API مخصوص محیط (توصیه می شود)
اگر پروژه‌های Firebase مختلفی را برای محیط‌های مختلف راه‌اندازی می‌کنید، مانند مرحله‌بندی و تولید، مهم است که هر نمونه برنامه با پروژه Firebase مربوطه خود تعامل داشته باشد. به عنوان مثال، نمونه برنامه استیجینگ شما هرگز نباید با پروژه Firebase تولیدی شما صحبت کند. این همچنین به این معنی است که برنامه مرحله‌بندی شما باید از کلیدهای API مرتبط با پروژه مرحله‌بندی Firebase شما استفاده کند.
برای کاهش مشکلات ترویج تغییرات کد از توسعه به مرحله‌بندی تا تولید، به جای قرار دادن کلیدهای API در خود کد، آنها را به عنوان متغیرهای محیطی تنظیم کنید یا در یک فایل پیکربندی قرار دهید.
توجه داشته باشید که اگر از مجموعه شبیه ساز محلی Firebase برای توسعه همراه با Firebase ML استفاده می کنید، باید یک کلید API فقط اشکال زدایی ایجاد و استفاده کنید. دستورالعمل های ایجاد این نوع کلید در اسناد Firebase ML یافت می شود.
سوالات متداول
برای تعیین اینکه کدام کلید API با برنامه Firebase شما مرتبط است، می توانید از یکی از گزینه های زیر استفاده کنید:
کنسول Firebase
به پروژه بروید و سپس به سمت پایین به کارت برنامه های شما بروید.
برنامه مورد علاقه را انتخاب کنید.
فایل/شیء پیکربندی Firebase را برای برنامه مورد نظر دریافت کنید و سپس کلید API آن را پیدا کنید:
Apple :
GoogleService-Info.plistرا دانلود کنید و سپس قسمتAPI_KEYرا پیدا کنیدAndroid :
google-services.jsonرا دانلود کنید، پیکربندی برنامه مورد نظر را پیدا کنید (نام بسته آن را جستجو کنید)، و سپس فیلدcurrent_keyرا پیدا کنید.Web : گزینه Config را انتخاب کنید و سپس قسمت
apiKeyرا پیدا کنید
Firebase CLI
با اجرای دستور زیر، فایل/شیء پیکربندی Firebase را برای برنامه مورد نظر دریافت کنید:
firebase apps:sdkconfig PLATFORM FIREBASE_APP_ID
- PLATFORM (یکی از):
IOS|ANDROID|WEB - FIREBASE_APP_ID : شناسه منحصر به فرد اختصاص داده شده توسط Firebase برای برنامه Firebase شما ( شناسه برنامه خود را پیدا کنید )
- PLATFORM (یکی از):
در پیکربندی Firebase چاپ شده برنامه، کلید API آن را پیدا کنید:
Apple : فیلد
API_KEYرا پیدا کنیدAndroid : پیکربندی برنامه مورد نظر را پیدا کنید (نام بسته آن را جستجو کنید)، و سپس فیلد
current_keyرا پیدا کنیدوب : فیلد
apiKeyرا پیدا کنید
REST API
apiKeyId(UID) کلید API را با فراخوانی نقطه پایانی قابل اجرا برای برنامه مورد نظر، و سپس ارسال مقدارapiKeyIdبه مرحله بعد، دریافت کنید.- اپل : با
projects.iosApps.getتماس بگیرید - Android : با
projects.androidApps.getتماس بگیرید - وب : با
projects.webApps.getتماس بگیرید
- اپل : با
رشته کلید API را با فراخوانی
projects.locations.keys.getKeyStringدریافت کنید.این
keyStringهمان مقداری است که در آرتیفکت پیکربندی برنامه ( اپل | اندروید | وب ) یافت می شود.
Firebase Apple Apps – هر برنامه فایل پیکربندی مخصوص به خود را دارد و می تواند تنها یک کلید API را در لیست داشته باشد.
برنامه‌های Android Firebase - همه برنامه‌های Android در پروژه Firebase در یک فایل پیکربندی فهرست شده‌اند و هر برنامه فقط می‌تواند یک کلید API فهرست شده داشته باشد. با این حال، هر برنامه در این فایل پیکربندی می‌تواند یک کلید متفاوت در لیست داشته باشد.
برنامه های وب Firebase - هر برنامه دارای شی پیکربندی خاص خود است و می تواند فقط یک کلید API را در لیست داشته باشد.
با این حال، می توانید از چندین کلید API با یک برنامه استفاده کنید. شما باید مکانیزمی را برای برنامه خود فراهم کنید تا به این کلیدهای API دیگر دسترسی داشته باشد، مانند یک متغیر محیطی. مکانیسم دسترسی به سایر کلیدهای API نمی تواند به فهرست آن کلیدهای API در فایل/شیء پیکربندی Firebase بستگی داشته باشد.
هنگامی که برای اولین بار فایل/شیء پیکربندی Firebase برنامه خود را دریافت می‌کنید ، Firebase بررسی می‌کند که آیا کلیدهای API موجود در پروژه شما دارای «محدودیت‌های برنامه» هستند که با برنامه مطابقت دارند (به عنوان مثال، شناسه بسته منطبق برای برنامه Apple).
اگر Firebase هیچ کلید محدودی را پیدا نکرد که مطابقت داشته باشد، iOS key برای برنامه‌های Apple، Android key Android برای برنامه‌های Android و Browser key برای برنامه‌های وب را در فایل پیکربندی/اشیاء فهرست می‌کند (با فرض وجود این کلیدها و هیچ "محدودیت برنامه" وجود ندارد که آنها را از مطابقت با آن برنامه باز دارد).
بله، می‌توانید کلید API خود را به صورت دستی از فایل/شیء پیکربندی خود حذف کنید. با این حال، شما باید مکانیسم دیگری برای دسترسی برنامه خود به یک کلید API (مانند از طریق یک متغیر محیطی) فراهم کنید. در غیر این صورت، هر تماسی با خدمات Firebase ناموفق خواهد بود.
بله، می‌توانید به صورت دستی یک فایل/شیء پیکربندی را ویرایش کنید تا یک کلید API دیگر را با یک برنامه مرتبط کنید.
توجه داشته باشید که اگر فایل/شیء پیکربندی برنامه خود را مجدداً از کنسول دریافت کنید، همیشه کلیدهای API را که Firebase به طور خودکار با آن برنامه مطابقت می‌دهد فهرست می‌کند. بنابراین، در صورت نیاز، باید ویرایش های دستی خود را تکرار کنید.
خیر، یک کلید API فقط یک پروژه خاص را شناسایی می کند و نمی تواند به پروژه دیگری منتقل شود.
در اینجا چند مورد از رایج ترین دلایل کلیدهای API نامعتبر آورده شده است:
کلید API دارای «محدودیت‌های کلیدی API» روی آن اعمال شده است که باعث می‌شود آن را با برنامه‌ای که تلاش می‌کند از کلید استفاده کند («محدودیت‌های برنامه») یا برای API نام‌گذاری شده غیرقابل استفاده («محدودیت‌های API») مطابقت نداشته باشد.
کلید API از پروژه در Google Cloud Console حذف شد.
کلید API برای شناسه پروژه فهرست شده در فایل/شیء پیکربندی Firebase برنامه ایجاد نشده است.
یکی از راه های رفع این مشکل این است که نسخه به روز شده فایل/شیء پیکربندی Firebase برنامه خود را دریافت کنید ، سپس فایل/شیء پیکربندی قدیمی خود را با فایل/شیء به روز شده جدید جایگزین کنید. قبل از ارسال یک فایل پیکربندی برای دانلود یا نمایش یک شیء پیکربندی در کنسول، Firebase بررسی می‌کند که کلید(های) API فهرست شده با برنامه(های) مطابقت داشته باشد.
کلید API استفاده شده توسط برنامه وب شما احتمالاً دارای "محدودیت های API" است. در این صورت، مطمئن شوید که Firebase Management API در لیست API های مجاز است.
اگر یک کلید API را که توسط یک برنامه استفاده می شود حذف کنید، تماس های API از آن برنامه با شکست مواجه می شوند. ممکن است گزارش‌ها، ایمیل‌ها یا خطاهایی دریافت کنید که می‌خواهید از کلید API استفاده کنید که نامعتبر است.
حذف یک کلید API دائمی است و قابل بازگشت نیست.