با استفاده از Hosting REST API در سایت خود مستقر شوید

Firebase Hosting REST API استقرار برنامه‌ریزی‌شده و قابل تنظیم در سایت‌های میزبانی شده توسط Firebase را فعال می‌کند. از این API REST برای استقرار محتوا و پیکربندی Hosting جدید یا به روز شده استفاده کنید.

به عنوان جایگزینی برای استفاده از Firebase CLI برای استقرار، می‌توانید از Firebase Hosting REST API برای ایجاد برنامه‌نویسی version جدیدی از دارایی‌ها برای سایت خود، آپلود فایل‌ها در نسخه و سپس استقرار نسخه در سایت خود استفاده کنید.

به عنوان مثال، با Firebase Hosting REST API، می توانید:

  • زمانبندی استقرارها با استفاده از REST API همراه با cron job، می توانید محتوای میزبانی شده توسط Firebase را بر اساس یک برنامه منظم تغییر دهید (به عنوان مثال، برای استقرار یک نسخه ویژه تعطیلات یا رویداد مربوط به محتوای خود).

  • ادغام با ابزارهای توسعه دهنده می‌توانید در ابزار خود گزینه‌ای ایجاد کنید تا پروژه‌های برنامه وب خود را در Firebase Hosting تنها با استفاده از یک کلیک (به عنوان مثال، کلیک کردن بر روی دکمه استقرار در یک IDE) اجرا کنید.

  • زمانی که محتوای استاتیک تولید می شود، به طور خودکار مستقر می شود. وقتی فرآیندی محتوای ثابت را به صورت برنامه‌نویسی تولید می‌کند (مثلاً محتوای تولید شده توسط کاربر مانند یک ویکی یا یک مقاله خبری)، شما می‌توانید محتوای تولید شده را به‌عنوان فایل‌های ثابت به‌جای ارائه‌ی پویا به آن‌ها گسترش دهید. این باعث صرفه جویی در توان محاسباتی گران قیمت می شود و فایل های شما را به روشی مقیاس پذیرتر ارائه می دهد.

این راهنما ابتدا نحوه فعال کردن، احراز هویت و مجوز API را شرح می‌دهد. سپس این راهنما از طریق یک مثال برای ایجاد یک نسخه Firebase Hosting ، برای آپلود فایل‌های مورد نیاز در نسخه، و سپس در نهایت برای استقرار نسخه استفاده می‌کند.

همچنین می‌توانید درباره این API REST در مستندات مرجع کامل Hosting REST API اطلاعات بیشتری کسب کنید.

قبل از شروع: REST API را فعال کنید

باید Firebase Hosting REST API را در کنسول Google APIs فعال کنید:

  1. صفحه Firebase Hosting API را در کنسول Google APIs باز کنید.

  2. وقتی از شما خواسته شد، پروژه Firebase خود را انتخاب کنید.

  3. در صفحه Firebase Hosting API روی Enable کلیک کنید.

مرحله 1: یک نشانه دسترسی برای احراز هویت و مجوز درخواست های API دریافت کنید

پروژه‌های Firebase از حساب‌های سرویس Google پشتیبانی می‌کنند که می‌توانید از آنها برای فراخوانی APIهای سرور Firebase از سرور برنامه یا محیط مورد اعتماد خود استفاده کنید. اگر در حال توسعه کد به صورت محلی یا نصب برنامه خود در محل هستید، می توانید از اعتبارنامه های به دست آمده از طریق این حساب سرویس برای تأیید درخواست های سرور استفاده کنید.

برای احراز هویت یک حساب سرویس و اجازه دسترسی به خدمات Firebase، باید یک فایل کلید خصوصی با فرمت JSON ایجاد کنید.

برای ایجاد یک فایل کلید خصوصی برای حساب سرویس خود:

  1. در کنسول Firebase ، تنظیمات > حساب‌های سرویس را باز کنید.

  2. روی Generate New Private Key کلیک کنید، سپس با کلیک روی Generate Key تأیید کنید.

  3. فایل JSON حاوی کلید را ایمن ذخیره کنید.

برای بازیابی رمز دسترسی کوتاه مدت OAuth 2.0، از اعتبارنامه Firebase خود به همراه کتابخانه Google Auth برای زبان دلخواه خود استفاده کنید:

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: مطمئن شوید که پروژه شما دارای یک سایت Hosting پیش فرض است

قبل از اولین استقرار شما در Firebase Hosting ، پروژه Firebase شما باید یک SITE Hosting پیش فرض داشته باشد.

  1. با تماس با نقطه پایانی sites.list بررسی کنید که آیا پروژه شما قبلاً یک سایت Hosting پیش فرض دارد یا خیر.

    به عنوان مثال:

    دستور 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 پیش فرض خود توصیه می کنیم. با نحوه یافتن این شناسه در پروژه های Understand 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

    این فراخوانی 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. با استفاده از SITE_ID خود در تماس، با نسخه نهایی versions.create تماس بگیرید.

    (اختیاری) همچنین می توانید یک شی پیکربندی 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"
      }
    }]
  }
}

این فراخوانی 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 بگویید کدام فایل‌ها را می‌خواهید در نهایت در این نسخه جدید مستقر کنید.

توجه داشته باشید که Hosting دارای حداکثر حجم 2 گیگابایت برای فایل های جداگانه است.

این API مستلزم آن است که فایل ها را با هش SHA256 شناسایی کنید. بنابراین، قبل از اینکه بتوانید فراخوانی API را انجام دهید، ابتدا باید یک هش برای هر فایل استاتیک را با 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 

    $ 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 

    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 به‌روزرسانی کنید.

با فیلد status در درخواست API خود که روی FINALIZED تنظیم شده است، با نقطه پایانی versions.patch تماس بگیرید.

به عنوان مثال:

دستور 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"}

این فراخوانی 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 

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 شما قابل دسترسی هستند.

همچنین می‌توانید نسخه جدید خود را در داشبورد Hosting کنسول Firebase فهرست کنید.