النشر إلى موقعك الإلكتروني باستخدام واجهة برمجة تطبيقات Hosting REST

تتيح Firebase Hosting REST API عمليات النشر الآلي والمخصّص للمواقع المستضافة على Firebase. استخدِم واجهة برمجة التطبيقات REST API هذه لنشر محتوى Hosting جديد أو معدَّل و إعدادات.

كبديل لاستخدام Firebase CLI لعمليات النشر، يمكنك استخدام Firebase Hosting REST API لإنشاء version جديد من مواد العرض لموقعك الإلكتروني بشكل آلي، وتحميل الملفات إلى الإصدار، ثم نشر الإصدار على موقعك الإلكتروني.

على سبيل المثال، باستخدام Firebase Hosting REST API، يمكنك إجراء ما يلي:

  • جدولة عمليات النشر باستخدام واجهة برمجة تطبيقات REST مع مهمة cron، يمكنك تغيير المحتوى المستضاف على Firebase وفقًا لجدول زمني منتظم (على سبيل المثال، لنشر إصدار خاص من المحتوى بمناسبة عطلة أو حدث).

  • الدمج مع أدوات المطوّرين: يمكنك إنشاء خيار في أداتك ل نشر مشاريع تطبيقات الويب على Firebase Hosting بنقرة واحدة فقط (مثل النقر على زر نشر ضمن بيئة تطوير متكاملة).

  • يتمّ نشر عمليات النشر المبرمَجة عند إنشاء محتوى ثابت. عندما تُنشئ عملية محتوًى ثابتًا آليًا (مثل المحتوى الذي ينشئه المستخدمون، مثل ملفات ويكي أو مقالات إخبارية)، يمكنك نشر المحتوى الذي تم إنشاؤه كملفّات ثابتة بدلاً من عرضه ديناميكيًا. ويساعدك ذلك في توفير طاقة الحوسبة الباهظة التكلفة وعرض ملفاتك بطريقة أكثر قابلية للتوسّع.

يوضّح هذا الدليل أولاً كيفية تفعيل واجهة برمجة التطبيقات والمصادقة عليها وتفويضها. بعد ذلك، يعرض هذا الدليل مثالاً لإنشاء نسخة Firebase Hosting وتحميل الملفات المطلوبة إلى الإصدار ثم أخيرًا نشر الإصدار.

يمكنك أيضًا الاطّلاع على مزيد من المعلومات عن واجهة برمجة التطبيقات REST API هذه في المستندات المرجعية الكاملة Hosting لواجهة برمجة التطبيقات REST API.

قبل البدء: تفعيل واجهة برمجة التطبيقات REST

يجب تفعيل واجهة برمجة التطبيقات Firebase Hosting REST API في وحدة تحكّم Google APIs:

  1. افتح صفحة واجهة برمجة التطبيقات Firebase Hosting في وحدة تحكّم Google APIs.

  2. اختَر مشروعك على Firebase عندما يُطلب منك ذلك.

  3. انقر على تفعيل في صفحة واجهة برمجة التطبيقات Firebase Hosting.

الخطوة 1: الحصول على رمز دخول لمصادقة طلبات واجهة برمجة التطبيقات والموافقة عليها

تتوافق مشاريع Firebase مع حسابات خدمة Google، التي يمكنك استخدامها لطلب واجهات برمجة تطبيقات خادم Firebase من خادم تطبيقك أو بيئة موثوق بها. إذا كنت تطوّر رمزًا محليًا أو تنشر تطبيقك داخل المؤسسة، يمكنك استخدام بيانات الاعتماد التي تم الحصول عليها من خلال حساب الخدمة هذا للسماح بطلبات الخادم.

لمصادقة حساب خدمة ومنحه الإذن بالوصول إلى خدمات Firebase، يجب إنشاء ملف مفتاح خاص بتنسيق JSON.

لإنشاء ملف مفتاح خاص لحساب الخدمة:

  1. في وحدة تحكّم Firebase، افتح الإعدادات > حسابات الخدمة.

  2. انقر على إنشاء مفتاح خاص جديد، ثم أكِّد ذلك بالنقر على إنشاء مفتاح.

  3. تخزين ملف JSON الذي يحتوي على المفتاح بأمان

استخدِم بيانات اعتماد Firebase مع مكتبة Google Auth Library بلغتك المفضّلة لاسترداد رمز وصول صالح لفترة قصيرة من خلال بروتوكول 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);
    });
  });
}

في هذا المثال، تُجري مكتبة برامج 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 تلقائيًا.

  1. تحقَّق ممّا إذا كان مشروعك يتضمّن موقعًا إلكترونيًا تلقائيًا على 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 موقع إلكتروني تلقائي. أكمِل باقي هذه الخطوة.

  2. اختَر SITE_ID لموقعك الإلكتروني التلقائي على Hosting. يُرجى مراعاة النقاط التالية عند اتخاذ هذا القرار SITE_ID:

    • يتم استخدام هذا الرمز SITE_ID لإنشاء النطاقات الفرعية التلقائية في Firebase:
      SITE_ID.web.app و SITE_ID.firebaseapp.com.

    • يجب استيفاء المتطلبات التالية في SITE_ID:

      • يجب أن يكون تصنيف اسم مضيف صالحًا، أي لا يمكن أن يحتوي على . أو _ أو غير ذلك.
      • يجب ألا يزيد عدد الأحرف عن 30 حرفًا.
      • يجب أن يكون فريدًا على مستوى Firebase

    يُرجى العِلم أنّنا ننصح غالبًا باستخدام رقم تعريف مشروعك كSITE_ID لموقعك الإلكتروني Hosting التلقائي. اطّلِع على كيفية العثور على هذا المعرّف في مقالة فهم مشاريع Firebase.

  3. أنشئ موقعك الإلكتروني التلقائي على 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 جديد لموقعك الإلكتروني. وفي وقت لاحق من هذا الدليل، ستُحمِّل الملفات إلى هذا الإصدار ثم تنشره على موقعك الإلكتروني.

  1. حدِّد SITE_ID للموقع الإلكتروني الذي تريد النشر فيه.

  2. اتصل بنقطة نهاية 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.

  1. ضغط الملفات باستخدام Gzip:

    gzip file1 && gzip file2 && gzip file3

    لديك الآن ثلاثة ملفات مضغوطة هي file1.gz وfile2.gz وfile3.gz.

  2. يمكنك الحصول على تجزئة SHA256 لكل ملف مضغوط:

    cat file1.gz | openssl dgst -sha256

66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4

    cat file2.gz | openssl dgst -sha256

490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083

    cat file3.gz | openssl dgst -sha256

59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315

    لديك الآن تجزئات SHA256 الثلاث للملفات الثلاثة المضغوطة.

  3. أرسِل هذه التجزئات الثلاث في طلب واجهة برمجة التطبيقات إلى نقطة النهاية 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 من الخطوة السابقة.

  1. يمكنك إلحاق شَرطة مائلة للأمام وتجزئة الملف إلى uploadUrl لإنشاء عنوان URL خاص بالملف بالتنسيق: https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH.

  2. حمِّل جميع الملفات المطلوبة واحدًا تلو الآخر (في هذا المثال، 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/file1
  • https://SITE_ID.web.app/file2
  • https://SITE_ID.web.app/file3

ويمكن الوصول إلى هذه الملفات أيضًا من خلال عناوين URL المرتبطة بنطاق SITE_ID.firebaseapp.com.

يمكنك أيضًا الاطّلاع على إصدارك الجديد في لوحة بيانات Hosting في وحدة تحكّم Firebase.