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

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

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

على سبيل المثال، باستخدام واجهة برمجة تطبيقات REST الخاصة بـ Firebase Hosting، يمكنك إجراء ما يلي:

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

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

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

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

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

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

عليك تفعيل واجهة برمجة تطبيقات REST الخاصة بـ Firebase Hosting في Google APIs console:

  1. افتح صفحة Firebase Hosting API في Google APIs console.

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

  3. انقر على تفعيل في صفحة Firebase Hosting API.

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

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

يمكنك الاطّلاع على جميع حسابات الخدمة لمشروعك على Firebase في علامة التبويب الإعدادات > حسابات الخدمة.

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

لإنشاء ملف مفتاح خاص لحساب الخدمة، اتّبِع الخطوات التالية:

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

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

  3. خزِّن ملف 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 web token أو 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

Java

private static String getAccessToken() throws IOException {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}

بعد انتهاء صلاحية رمز الدخول، يتم استدعاء طريقة إعادة تحميل الرمز تلقائيًا لاسترداد رمز دخول محدَّث.

Firebase Hosting

الخطوة 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. لذا، قبل إجراء طلب واجهة برمجة التطبيقات، عليك أولاً حساب تجزئة لكل ملف ثابت من خلال ضغط الملفات باستخدام Gzip، ثم الحصول على تجزئة 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: تعديل حالة الإصدار إلى FINALIZED

بعد تحميل جميع الملفات المُدرَجة في استجابة 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 dashboard of the Firebase console.