تتيح Firebase Hosting REST API عمليات النشر الآلي والمخصّص للمواقع المستضافة على Firebase. استخدِم واجهة برمجة التطبيقات REST API هذه لنشر محتوى Hosting جديد أو معدَّل و إعدادات.
كبديل لاستخدام Firebase CLI لعمليات النشر، يمكنك استخدام Firebase Hosting REST API لإنشاء version جديد من مواد العرض لموقعك الإلكتروني بشكل آلي، وتحميل الملفات إلى الإصدار، ثم نشر الإصدار على موقعك الإلكتروني.
على سبيل المثال، باستخدام Firebase Hosting REST API، يمكنك إجراء ما يلي:
تحديد موعد عمليات النشر باستخدام واجهة برمجة التطبيقات REST API مع إحدى مهام cron، يمكنك تغيير المحتوى المستضاف على Firebase بجدول زمني منتظم (على سبيل المثال، لطرح إصدار خاص من المحتوى الخاص بعطلة أو حدث).
الدمج مع أدوات المطوّرين: يمكنك إنشاء خيار في أداتك ل نشر مشاريع تطبيقات الويب على Firebase Hosting بنقرة واحدة فقط (مثل النقر على زر نشر ضمن بيئة تطوير متكاملة).
يتمّ نشر المحتوى التلقائي عند إنشاء محتوى ثابت. عندما تُنشئ عملية محتوًى ثابتًا آليًا (مثل المحتوى الذي ينشئه المستخدمون، مثل ملفات ويكي أو مقالات إخبارية)، يمكنك نشر المحتوى الذي تم إنشاؤه كملفّات ثابتة بدلاً من عرضه ديناميكيًا. ويساعدك ذلك في توفير طاقة الحوسبة الباهظة التكلفة وعرض ملفاتك بطريقة أكثر قابلية للتوسّع.
يوضّح هذا الدليل أولاً كيفية تفعيل واجهة برمجة التطبيقات والمصادقة عليها وتفويضها. بعد ذلك، يوضّح هذا الدليل مثالاً لإنشاء Firebase Hosting إصدار، وتحميل الملفات المطلوبة إلى الإصدار، ثم نشر الإصدار أخيرًا.
يمكنك أيضًا الاطّلاع على مزيد من المعلومات عن واجهة برمجة التطبيقات REST API هذه في المستندات المرجعية الكاملة Hosting لواجهة برمجة التطبيقات REST API.
قبل البدء: تفعيل واجهة برمجة التطبيقات REST
يجب تفعيل واجهة برمجة التطبيقات Firebase Hosting REST API في وحدة تحكّم Google APIs:
افتح صفحة واجهة برمجة التطبيقات Firebase Hosting في وحدة تحكّم Google APIs.
اختَر مشروعك على Firebase عندما يُطلب منك ذلك.
انقر على تفعيل في صفحة واجهة برمجة التطبيقات Firebase Hosting.
الخطوة 1: الحصول على رمز دخول لمصادقة طلبات واجهة برمجة التطبيقات والموافقة عليها
تتوافق مشاريع Firebase مع حسابات الخدمة في Google، والتي يمكنك استخدامها لاستدعاء واجهات برمجة تطبيقات خادم Firebase من خادم التطبيق أو البيئة الموثوق بها. إذا كنت تُطوّر الرمز البرمجي على الجهاز أو تنشر تطبيقك على الأجهزة، يمكنك استخدام بيانات الاعتماد التي تم الحصول عليها من خلال حساب الخدمة هذا لتفويض طلبات الخادم.
لمصادقة حساب خدمة وتفويضه للوصول إلى خدمات Firebase، عليك إنشاء ملف مفتاح خاص بتنسيق JSON.
لإنشاء ملف مفتاح خاص لحساب الخدمة:
في وحدة تحكّم Firebase، افتح الإعدادات > حسابات الخدمة.
انقر على إنشاء مفتاح خاص جديد، ثم أكِّد ذلك بالنقر على إنشاء مفتاح.
تخزين ملف JSON الذي يحتوي على المفتاح بأمان
استخدِم بيانات اعتماد Firebase مع مكتبة Google Auth Library بلغتك المفضّلة لاسترداد رمز وصول صالح لفترة قصيرة من خلال بروتوكول OAuth 2.0:
node.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); }); }); }
في هذا المثال، تُجري مكتبة برامج Google API مصادقة الطلب باستخدام رمز مميّز على شبكة JSON أو JWT. لمزيد من المعلومات، يُرجى الاطّلاع على رموز الويب المميّزة بتنسيق JSON.
Python
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(); }
بعد انتهاء صلاحية رمز الدخول، يتم استدعاء أسلوب إعادة تحميل الرمز تلقائيًا لاسترداد رمز دخول معدَّل.
الخطوة 2: التأكّد من أنّ مشروعك يتضمّن موقعًا إلكترونيًا Hosting تلقائيًا
قبل عملية النشر الأولى على Firebase Hosting، يجب أن يحتوي مشروعك على Firebase
على Hosting SITE تلقائيًا.
تحقَّق ممّا إذا كان مشروعك يتضمّن موقعًا إلكترونيًا تلقائيًا على Hosting من خلال طلب نقطة نهاية
sites.list.على سبيل المثال:
أمر 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.appSITE_ID.firebaseapp.comيجب استيفاء المتطلبات التالية في
SITE_ID:- يجب أن يكون تصنيف اسم مضيف صالحًا، أي لا يمكن أن يحتوي على
.أو_أو غير ذلك. - يجب ألا يزيد عدد الأحرف عن 30 حرفًا.
- يجب أن يكون فريدًا على مستوى Firebase.
- يجب أن يكون تصنيف اسم مضيف صالحًا، أي لا يمكن أن يحتوي على
تجدر الإشارة إلى أنّنا ننصح غالبًا باستخدام رقم تعريف مشروعك ك
SITE_IDلموقعك الإلكتروني Hosting التلقائي. تعرَّف على كيفية العثور على هذا المعرّف في مقالة فهم مشاريع Firebase.أنشئ موقعك الإلكتروني التلقائي على Hosting من خلال طلب نقطة نهاية
sites.createباستخدامSITE_IDالمطلوب كمَعلمةsiteId.على سبيل المثال:
أمر 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
يعرض طلب البيانات من واجهة برمجة التطبيقات هذا المخصّص لموقع
sites.createملف JSON التالي:{ "name": "projects/PROJECT_ID/sites/SITE_ID", "defaultUrl": "https://SITE_ID.web.app", "type": "DEFAULT_SITE" }
الخطوة 3: إنشاء نسخة جديدة لموقعك الإلكتروني
الغرض من طلب البيانات الأول من واجهة برمجة التطبيقات هو إنشاء
Version جديد لموقعك الإلكتروني.
في وقت لاحق من هذا الدليل، ستحمّل الملفات إلى هذا الإصدار، ثم ستنظّمه على
موقعك الإلكتروني.
حدِّد SITE_ID للموقع الإلكتروني الذي تريد نشر التطبيق عليه.
اتصل بنقطة نهاية versions.create باستخدام SITE_ID في المكالمة.
(اختياري) يمكنك أيضًا تمرير كائن إعدادات 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" } }] } }
يعرض طلب البيانات من واجهة برمجة التطبيقات هذا المخصّص لموقع 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. ستحتاج إلى
هذا المعرّف الفريد في جميع أقسام هذا الدليل للإشارة إلى
هذه النسخة المحدّدة.
الخطوة 4: تحديد قائمة الملفات التي تريد نشرها
بعد أن حصلت على معرّف الإصدار الجديد، عليك إخبار Firebase Hosting بالملفات التي تريد نشرها في الإصدار الجديد هذا.
يُرجى العِلم أنّ الحد الأقصى المسموح به لحجم Hosting هو 2 غيغابايت بالنسبة إلى الملفات الفردية.
تتطلّب واجهة برمجة التطبيقات هذه تحديد الملفات باستخدام تجزئة SHA256. لذلك، قبل أن تتمكّن من إجراء طلب البيانات من واجهة برمجة التطبيقات، عليك أولاً احتساب تجزئة لكل ملف ثابت من خلال ضغط الملفات ثم الحصول على تجزئة 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 الثلاث للملفّات الثلاثة المضغوطة.
أرسِل هذه التجزئات الثلاث في طلب واجهة برمجة التطبيقات إلى نقطة النهاية
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" } }
يعرض طلب البيانات من واجهة برمجة التطبيقات هذا المخصّص لموقع 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.
الخطوة 5: تحميل الملفات المطلوبة
عليك تحميل كل ملف مطلوب بشكلٍ فردي (هذه الملفات مُدرَجة في 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
تؤدي عمليات التحميل الناجحة إلى عرض استجابة HTTPS 200 OK.
الخطوة 6: تعديل حالة الإصدار إلى "مكتملة"
بعد تحميل جميع الملفات المدرَجة في استجابة
versions.populateFiles، يمكنك تعديل حالة إصدارك إلى
FINALIZED.
استخدِم نقطة نهاية versions.patch
مع ضبط الحقل status في طلب البيانات من واجهة برمجة التطبيقات على FINALIZED.
على سبيل المثال:
أمر 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"}
يعرض طلب البيانات من واجهة برمجة التطبيقات هذا إلى 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" }
الخطوة 7: طرح الإصدار للنشر
بعد أن أصبحت لديك نسخة نهائية، يمكنك إصدارها للنشر. لهذه الخطوة،
عليك إنشاء
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
يعرض طلب البيانات من واجهة برمجة التطبيقات هذا المخصّص لموقع 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/file1https://SITE_ID.web.app/file2https://SITE_ID.web.app/file3
يمكن أيضًا الوصول إلى هذه الملفات من خلال عناوين URL المرتبطة بنطاق
SITE_ID.firebaseapp.com.
يمكنك أيضًا الاطّلاع على إصدارك الجديد في لوحة بيانات Hosting في وحدة تحكّم Firebase.