انشر على موقعك باستخدام Hosting REST API

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

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

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

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

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

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

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

يمكنك أيضًا معرفة المزيد حول REST API في الوثائق المرجعية الكاملة لـ Hosting REST API .

قبل أن تبدأ: قم بتمكين REST API

يجب عليك تمكين Firebase Hosting REST API في وحدة تحكم Google APIs:

  1. افتح صفحة Firebase Hosting API في وحدة تحكم Google APIs.

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

  3. انقر فوق "تمكين" في صفحة Firebase Hosting API.

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

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

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

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

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

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

  3. قم بتخزين ملف JSON الذي يحتوي على المفتاح بشكل آمن.

استخدم بيانات اعتماد Firebase الخاصة بك مع مكتبة Google Auth للغتك المفضلة لاسترداد رمز وصول 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 .

بايثون

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 -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 -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.create ملف JSON التالي:

    {
      "name": "projects/PROJECT_ID/sites/SITE_ID",
      "defaultUrl": "https://SITE_ID.web.app",
      "type": "DEFAULT_SITE"
    }
    

الخطوة 3: إنشاء نسخة جديدة لموقعك

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

  1. حدد SITE_ID للموقع الذي تريد النشر عليه.

  2. اتصل بنقطة نهاية versions.create باستخدام SITE_ID الخاص بك في المكالمة.

    (اختياري) يمكنك أيضًا تمرير كائن تكوين Firebase Hosting في المكالمة، بما في ذلك تعيين رأس يقوم بتخزين جميع الملفات مؤقتًا لمدة زمنية محددة.

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

    أمر الضفيرة

    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 . ستحتاج إلى هذا المعرف الفريد خلال هذا الدليل للإشارة إلى هذا الإصدار المحدد.

الخطوة 4: حدد قائمة الملفات التي تريد نشرها

الآن بعد أن أصبح لديك معرف الإصدار الجديد، يتعين عليك إخبار Firebase Hosting بالملفات التي تريد نشرها في النهاية في هذا الإصدار الجديد.

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

تتطلب واجهة برمجة التطبيقات هذه تحديد الملفات من خلال تجزئة SHA256. لذلك، قبل أن تتمكن من إجراء استدعاء واجهة برمجة التطبيقات، ستحتاج أولاً إلى حساب تجزئة لكل ملف ثابت عن طريق ضغط الملفات باستخدام Gziping ثم أخذ تجزئة 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. أرسل هذه التجزئات الثلاثة في طلب واجهة برمجة التطبيقات (API) إلى نقطة نهاية versions.populateFiles . قم بإدراج كل تجزئة حسب المسار المطلوب للملف الذي تم تحميله (في هذا المثال، /file1 و /file2 و /file3 ).

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

    أمر الضفيرة

    $ 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 .

الخطوة 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 -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.

الخطوة 6: قم بتحديث حالة الإصدار إلى FINALIZED

بعد قيامك بتحميل جميع الملفات المدرجة في استجابة versions.populateFiles ، يمكنك تحديث حالة الإصدار الخاص بك إلى FINALIZED .

اتصل بنقطة نهاية versions.patch مع تعيين حقل status في طلب واجهة برمجة التطبيقات (API) الخاص بك على FINALIZED .

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

أمر الضفيرة

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"
}

الخطوة 7: قم بإصدار الإصدار للنشر

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

قم باستدعاء نقطة النهاية releases.create لإنشاء الإصدار الخاص بك.

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

أمر الضفيرة

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 .

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