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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يمكنك استخدام بيانات اعتماد Firebase مع مكتبة مصادقة Google لاسترداد رمز الدخول إلى 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: التأكّد من أنّ مشروعك يتضمّن موقع استضافة تلقائيًا

قبل عملية النشر الأولى في "استضافة Firebase"، يجب أن يكون مشروعك في Firebase أن يكون له إعداد تلقائي استضافة SITE.

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

    • إذا حصلت على صفيف فارغ، هذا يعني أنّه ليست لديك استضافة تلقائية. موقعك. أكمِل باقي هذه الخطوة.

  2. حدِّد SITE_ID لموقع الاستضافة التلقائي. إبقاء يجب أخذ التالي في الاعتبار عند تحديد SITE_ID:

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

    • يتضمّن SITE_ID المتطلبات التالية:

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

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

  3. يمكنك إنشاء موقع الاستضافة التلقائي من خلال طلب 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" في المكالمة، بما في ذلك إعداد عنوان يُخزّن جميع الملفات في ذاكرة التخزين المؤقت وطول الوقت.

    على سبيل المثال:

    الأمر 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: تحديد قائمة الملفات التي تريد نشرها

الآن بعد أن حصلت على معرّف الإصدار الجديد، عليك إخبار تتيح لك هذه الخدمة استضافة الملفات التي تريد نشرها في هذا القسم الجديد. .

يُرجى ملاحظة أن خدمة الاستضافة تحتوي على حد أقصى للحجم يبلغ 2 غيغابايت الملفات الفردية.

تتطلّب واجهة برمجة التطبيقات هذه تحديد الملفات باستخدام تجزئة SHA256. لذا، قبل أن تتمكن من لطلب بيانات من واجهة برمجة التطبيقات، ستحتاج أولاً إلى حساب تجزئة لكل ملف ثابت من خلال الضغط بتنسيق Gzip للملفات ثم الحصول على تجزئة SHA256 لكل ملف مضغوط حديثًا.

استكمالاً لمثالنا، لنفترض أنك تريد نشر ثلاثة ملفات في واجهة برمجة تطبيقات الإصدار: file1 وfile2 وfile3.

  1. قم بضغط الملفات:

    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.

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