API REST Firebase Hosting امکان استقرارهای برنامه‌نویسی‌شده و قابل تنظیم را در سایت‌های میزبانی‌شده توسط فایربیس شما فراهم می‌کند. از این API REST برای استقرار محتوا و پیکربندی Hosting جدید یا به‌روز شده استفاده کنید.
به عنوان جایگزینی برای استفاده از Firebase CLI برای استقرارها، می‌توانید از Firebase Hosting REST API برای ایجاد برنامه‌نویسی‌شده‌ی version جدیدی از دارایی‌ها برای سایت خود، آپلود فایل‌ها به این نسخه و سپس استقرار نسخه در سایت خود استفاده کنید.
برای مثال، با Firebase Hosting REST API، می‌توانید:
زمانبندی استقرارها. با استفاده از REST API همراه با یک cron job، می‌توانید محتوای میزبانی‌شده توسط Firebase را طبق یک برنامه منظم تغییر دهید (برای مثال، برای استقرار یک نسخه ویژه تعطیلات یا مرتبط با رویداد از محتوای خود).
ادغام با ابزارهای توسعه‌دهندگان. شما می‌توانید در ابزار خود گزینه‌ای ایجاد کنید تا پروژه‌های برنامه وب خود را تنها با یک کلیک (مثلاً کلیک روی دکمه استقرار در یک IDE) در Firebase Hosting مستقر کنید.
وقتی محتوای استاتیک تولید می‌شود، خودکارسازی (Automate) اجرا می‌شود. وقتی یک فرآیند محتوای استاتیک را به صورت برنامه‌نویسی‌شده تولید می‌کند (مثلاً محتوای تولیدشده توسط کاربر مانند ویکی یا یک مقاله خبری)، می‌توانید محتوای تولیدشده را به جای ارائه پویا، به صورت فایل‌های استاتیک اجرا کنید. این کار باعث صرفه‌جویی در قدرت محاسباتی پرهزینه شما می‌شود و فایل‌های شما را به روشی مقیاس‌پذیرتر ارائه می‌دهد.
این راهنما ابتدا نحوه فعال‌سازی، احراز هویت و مجوزدهی API را شرح می‌دهد. سپس این راهنما با مثالی نحوه ایجاد نسخه Firebase Hosting ، آپلود فایل‌های مورد نیاز به این نسخه و در نهایت استقرار نسخه را شرح می‌دهد.
همچنین می‌توانید اطلاعات بیشتری در مورد این REST API را در مستندات مرجع کامل Hosting REST API بیابید.
قبل از شروع: فعال کردن REST API
شما باید Firebase Hosting REST API را در کنسول Google APIs فعال کنید:
صفحه Firebase Hosting API را در کنسول Google APIs باز کنید.
وقتی از شما خواسته شد، پروژه Firebase خود را انتخاب کنید.
در صفحه Firebase Hosting API روی فعال کردن (Enable) کلیک کنید.
مرحله ۱: دریافت توکن دسترسی برای احراز هویت و مجوزدهی درخواست‌های API
پروژه‌های فایربیس از حساب‌های سرویس گوگل پشتیبانی می‌کنند که می‌توانید از آنها برای فراخوانی APIهای سرور فایربیس از سرور برنامه یا محیط مورد اعتماد خود استفاده کنید. اگر در حال توسعه کد به صورت محلی هستید یا برنامه خود را در محل مستقر می‌کنید، می‌توانید از اعتبارنامه‌های به دست آمده از طریق این حساب سرویس برای تأیید درخواست‌های سرور استفاده کنید.
برای تأیید اعتبار یک حساب کاربری سرویس و اجازه دسترسی آن به سرویس‌های Firebase، باید یک فایل کلید خصوصی با فرمت JSON ایجاد کنید.
برای ایجاد یک فایل کلید خصوصی برای حساب سرویس خود:
در کنسول Firebase ، تنظیمات > حساب‌های سرویس (Settings > Service Accounts) را باز کنید.
روی «ایجاد کلید خصوصی جدید» کلیک کنید، سپس با کلیک روی «ایجاد کلید» تأیید کنید.
فایل JSON حاوی کلید را به طور ایمن ذخیره کنید.
از اعتبارنامه‌های Firebase خود به همراه کتابخانه Google Auth برای زبان مورد نظر خود استفاده کنید تا یک توکن دسترسی OAuth 2.0 کوتاه مدت دریافت کنید:
گره.js
const {google} = require('googleapis'); function getAccessToken() { return new Promise(function(resolve, reject) { var key = require('./service-account.json'); var jwtClient = new google.auth.JWT( key.client_email, null, key.private_key, SCOPES, null ); jwtClient.authorize(function(err, tokens) { if (err) { reject(err); return; } resolve(tokens.access_token); }); }); }
در این مثال، کتابخانه کلاینت API گوگل، درخواست را با یک توکن وب JSON یا JWT احراز هویت می‌کند. برای اطلاعات بیشتر، به JSON web tokens مراجعه کنید.
پایتون
def _get_access_token(): """Retrieve a valid access token that can be used to authorize requests. :return: Access token. """ credentials = ServiceAccountCredentials.from_json_keyfile_name( 'service-account.json', SCOPES) access_token_info = credentials.get_access_token() return access_token_info.access_token
جاوا
private static String getAccessToken() throws IOException { GoogleCredential googleCredential = GoogleCredential .fromStream(new FileInputStream("service-account.json")) .createScoped(Arrays.asList(SCOPES)); googleCredential.refreshToken(); return googleCredential.getAccessToken(); }
پس از انقضای توکن دسترسی شما، متد به‌روزرسانی توکن به طور خودکار فراخوانی می‌شود تا توکن دسترسی به‌روزرسانی‌شده را بازیابی کند.
مرحله ۲: مطمئن شوید که پروژه شما یک سایت Hosting پیش‌فرض دارد
قبل از اولین استقرار در Firebase Hosting ، پروژه Firebase شما باید یک Hosting SITE پیش‌فرض داشته باشد.
با فراخوانی نقطه پایانی
sites.listبررسی کنید که آیا پروژه شما از قبل یک سایت Hosting پیش‌فرض دارد یا خیر.برای مثال:
دستور cURL
curl -H "Content-Type: application/json" \ -H "Authorization: Bearer ACCESS_TOKEN" \ https://firebasehosting.googleapis.com/v1beta1/projects/PROJECT_ID/sitesدرخواست HTTPS خام
Host: firebasehosting.googleapis.com POST /v1beta1/projects/PROJECT_ID/sites HTTP/1.1 Authorization: Bearer ACCESS_TOKEN Content-Type: application/json
اگر یکی از سایت‌ها دارای
"type": "DEFAULT_SITE"باشد، پروژه شما از قبل یک سایت Hosting پیش‌فرض دارد. از ادامه این مرحله صرف نظر کنید و به مرحله بعدی بروید: یک نسخه جدید برای سایت خود ایجاد کنید .اگر یک آرایه خالی دریافت کردید، پس سایت Hosting پیش‌فرض ندارید. بقیه این مرحله را انجام دهید.
SITE_IDرا برای سایت Hosting پیش‌فرض خود انتخاب کنید. هنگام انتخاب اینSITE_IDموارد زیر را در نظر داشته باشید:این
SITE_IDبرای ایجاد زیر دامنه‌های پیش‌فرض Firebase شما استفاده می‌شود:SITE_ID .web.appوSITE_ID .firebaseapp.comیک
SITE_IDالزامات زیر را دارد:- باید یک برچسب نام میزبان معتبر باشد، به این معنی که نمی‌تواند شامل
.،_و غیره باشد. - باید 30 کاراکتر یا کمتر باشد
- باید در Firebase به صورت سراسری منحصر به فرد باشد
- باید یک برچسب نام میزبان معتبر باشد، به این معنی که نمی‌تواند شامل
توجه داشته باشید که ما اغلب توصیه می‌کنیم از شناسه پروژه خود به عنوان
SITE_IDبرای سایت Hosting پیش‌فرض خود استفاده کنید. نحوه یافتن این شناسه را در بخش «درک پروژه‌های Firebase» بیاموزید.با فراخوانی نقطه پایانی
sites.createو با استفاده ازSITE_IDمورد نظر خود به عنوان پارامترsiteIdسایت Hosting پیش‌فرض خود را ایجاد کنید.برای مثال:
دستور cURL
curl -H "Content-Type: application/json" \ -H "Authorization: Bearer ACCESS_TOKEN" \ https://firebasehosting.googleapis.com/v1beta1/projects/PROJECT_ID/sites?siteId=SITE_IDدرخواست HTTPS خام
Host: firebasehosting.googleapis.com POST /v1beta1/projects/PROJECT_ID/sites?siteId=SITE_ID Authorization: Bearer ACCESS_TOKEN Content-Type: application/json
این فراخوانی API به
sites.createJSON زیر را برمی‌گرداند:{ "name": "projects/PROJECT_ID/sites/SITE_ID", "defaultUrl": "https://SITE_ID.web.app", "type": "DEFAULT_SITE" }
مرحله ۳: یک نسخه جدید برای سایت خود ایجاد کنید
اولین فراخوانی API شما ایجاد یک Version جدید برای سایتتان است. بعداً در این راهنما، فایل‌ها را در این نسخه آپلود می‌کنید، سپس آن را در سایت خود مستقر می‌کنید.
SITE_ID را برای سایتی که می‌خواهید در آن مستقر شوید، تعیین کنید.
با استفاده از SITE_ID خود در فراخوانی، نقطه پایانی versions.create را فراخوانی کنید.
(اختیاری) همچنین می‌توانید یک شیء پیکربندی Firebase Hosting در فراخوانی ارسال کنید، از جمله تنظیم یک هدر که تمام فایل‌ها را برای مدت زمان مشخصی ذخیره می‌کند.
برای مثال:
دستور cURL
curl -H "Content-Type: application/json" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -d '{ "config": { "headers": [{ "glob": "**", "headers": { "Cache-Control": "max-age=1800" } }] } }' \ https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versionsدرخواست HTTPS خام
Host: firebasehosting.googleapis.com POST /v1beta1/sites/SITE_ID/versions HTTP/1.1 Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Content-Length: 134 { "config": { "headers": [{ "glob": "**", "headers": { "Cache-Control": "max-age=1800" } }] } }
این فراخوانی API به versions.create JSON زیر را برمی‌گرداند:
{
"name": "sites/SITE_ID/versions/VERSION_ID",
"status": "CREATED",
"config": {
"headers": [{
"glob": "**",
"headers": {
"Cache-Control": "max-age=1800"
}
}]
}
}این پاسخ شامل یک شناسه منحصر به فرد برای نسخه جدید، به فرمت sites/ SITE_ID /versions/ VERSION_ID است. برای ارجاع به این نسخه خاص، در سراسر این راهنما به این شناسه منحصر به فرد نیاز خواهید داشت.
مرحله ۴: لیست فایل‌هایی را که می‌خواهید مستقر کنید مشخص کنید
حالا که شناسه نسخه جدید خود را دارید، باید به Firebase Hosting بگویید که می‌خواهید در نهایت کدام فایل‌ها را در این نسخه جدید مستقر کنید.
توجه داشته باشید که Hosting حداکثر اندازه ۲ گیگابایت برای فایل‌های تکی دارد.
این API مستلزم آن است که فایل‌ها را با استفاده از هش SHA256 شناسایی کنید. بنابراین، قبل از اینکه بتوانید فراخوانی API را انجام دهید، ابتدا باید با فشرده‌سازی فایل‌ها با Gzip و سپس گرفتن هش SHA256 از هر فایل تازه فشرده شده، یک هش برای هر فایل استاتیک محاسبه کنید.
در ادامه‌ی مثالمان، فرض کنید می‌خواهید سه فایل را در نسخه‌ی جدید مستقر کنید: file1 ، file2 و file3 .
فایل‌ها را Gzip کنید:
gzip file1 && gzip file2 && gzip file3
اکنون سه فایل فشرده
file1.gz،file2.gzوfile3.gzدارید.هش SHA256 هر فایل فشرده را دریافت کنید:
cat file1.gz | openssl dgst -sha256 66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4
cat file2.gz | openssl dgst -sha256 490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083
cat file3.gz | openssl dgst -sha256 59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315
اکنون سه هش SHA256 از سه فایل فشرده را دارید.
این سه هش را در یک درخواست API به نقطه پایانی
versions.populateFilesارسال کنید. هر هش را بر اساس مسیر مورد نظر برای فایل آپلود شده فهرست کنید (در این مثال،/file1،/file2و/file3).برای مثال:
دستور cURL
$ curl -H "Content-Type: application/json" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -d '{ "files": { "/file1": "66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4", "/file2": "490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083", "/file3": "59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315" } }' \ https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions/VERSION_ID:populateFilesدرخواست HTTPS خام
Host: firebasehosting.googleapis.com POST /v1beta1/sites/SITE_ID/versions/VERSION_ID:populateFiles HTTP/1.1 Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Content-Length: 181 { "files": { "/file1": "66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4", "/file2": "490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083", "/file3": "59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315" } }
این فراخوانی API به versions.populateFiles JSON زیر را برمی‌گرداند:
{ "uploadRequiredHashes": [ "490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083", "59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315" ], "uploadUrl": "https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files" }
این پاسخ شامل موارد زیر است:
هش هر فایلی که باید آپلود شود. برای مثال، در این مثال،
file1قبلاً در نسخه قبلی آپلود شده است، بنابراین هش آن در لیستuploadRequiredHashesقرار ندارد.uploadUrlکه مختص نسخه جدید است.
در مرحله بعدی برای آپلود دو فایل جدید، به هش‌ها و uploadURL از پاسخ versions.populateFiles نیاز خواهید داشت.
مرحله ۵: آپلود فایل‌های مورد نیاز
شما باید هر فایل مورد نیاز را به صورت جداگانه آپلود کنید (آن دسته از فایل‌هایی که در uploadRequiredHashes از پاسخ versions.populateFiles در مرحله قبل فهرست شده‌اند). برای آپلود این فایل‌ها، به هش‌های فایل و uploadUrl از مرحله قبل نیاز خواهید داشت.
یک اسلش (/) و هش فایل را به
uploadUrlاضافه کنید تا یک URL مخصوص فایل با فرمت زیر ایجاد شود:https://upload-firebasehosting.googleapis.com/upload/sites/ SITE_ID /versions/ VERSION_ID /files/ FILE_HASH.تمام فایل‌های مورد نیاز را یک به یک (در این مثال، فقط
file2.gzوfile3.gz) با استفاده از یک سری درخواست، در آدرس اینترنتی (URL) مخصوص فایل آپلود کنید.برای مثال، برای آپلود
file2.gz:دستور cURL
curl -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/octet-stream" \ --data-binary @./file2.gz \ https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASHدرخواست HTTPS خام
Host: upload-firebasehosting.googleapis.com POST /upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH HTTP/1.1 Authorization: Bearer ACCESS_TOKEN Content-Type: application/octet-stream Content-Length: 500 content-of-file2.gz
آپلودهای موفق، پاسخ 200 OK HTTPS را برمی‌گردانند.
مرحله ۶: وضعیت نسخه را به FINALIZED به‌روزرسانی کنید
پس از اینکه تمام فایل‌های فهرست‌شده در پاسخ versions.populateFiles را آپلود کردید، می‌توانید وضعیت نسخه خود را به FINALIZED به‌روزرسانی کنید.
با تنظیم فیلد status در درخواست API خود روی FINALIZED نقطه پایانی versions.patch فراخوانی کنید.
برای مثال:
دستور cURL
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X PATCH \
-d '{"status": "FINALIZED"}' \
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions/VERSION_ID?update_mask=status
درخواست HTTPS خام
Host: firebasehosting.googleapis.com PATCH /v1beta1/sites/SITE_ID/versions/VERSION_ID?update_mask=status HTTP/1.1 Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Content-Length: 23 {"status": "FINALIZED"}
این فراخوانی API به versions.patch JSON زیر را برمی‌گرداند. بررسی کنید که status به FINALIZED به‌روزرسانی شده باشد.
{ "name": "sites/SITE_ID/versions/VERSION_ID", "status": "FINALIZED", "config": { "headers": [{ "glob": "**", "headers": {"Cache-Control": "max-age=1800"} }] }, "createTime": "2018-12-02T13:41:56.905743Z", "createUser": { "email": "SERVICE_ACCOUNT_EMAIL@SITE_ID.iam.gserviceaccount.com" }, "finalizeTime": "2018-12-02T14:56:13.047423Z", "finalizeUser": { "email": "USER_EMAIL@DOMAIN.tld" }, "fileCount": "5", "versionBytes": "114951" }
مرحله ۷: انتشار نسخه برای استقرار
حالا که نسخه نهایی را دارید، آن را برای استقرار منتشر کنید. برای این مرحله، باید یک Release از نسخه خود ایجاد کنید که شامل پیکربندی میزبانی و تمام فایل‌های محتوا برای نسخه جدید شما باشد.
برای ایجاد نسخه خود، نقطه پایانی releases.create را فراخوانی کنید.
برای مثال:
دستور cURL
curl -H "Authorization: Bearer ACCESS_TOKEN" \
-X POST
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/releases?versionName=sites/SITE_ID/versions/VERSION_ID
درخواست HTTPS خام
Host: firebasehosting.googleapis.com POST /v1beta1/sites/SITE_ID/releases?versionName=sites/SITE_ID/versions/VERSION_ID HTTP/1.1 Authorization: Bearer ACCESS_TOKEN
این فراخوانی API برای releases.create JSON زیر را برمی‌گرداند:
{ "name": "sites/SITE_ID/releases/RELEASE_ID", "version": { "name": "sites/SITE_ID/versions/VERSION_ID", "status": "FINALIZED", "config": { "headers": [{ "glob": "**", "headers": {"Cache-Control": "max-age=1800"} }] } }, "type": "DEPLOY", "releaseTime": "2018-12-02T15:14:37Z" }
پیکربندی میزبانی و تمام فایل‌های نسخه جدید اکنون باید در سایت شما مستقر شده باشند و می‌توانید با استفاده از URLها به فایل‌های خود دسترسی پیدا کنید:
-
https:// SITE_ID .web.app/file1 -
https:// SITE_ID .web.app/file2 -
https:// SITE_ID .web.app/file3
این فایل‌ها همچنین از طریق URL های مرتبط با دامنه SITE_ID .firebaseapp.com شما قابل دسترسی هستند.
همچنین می‌توانید نسخه جدید خود را که در داشبورد Hosting کنسول Firebase فهرست شده است، مشاهده کنید.