Firebase 将于 5 月 14 日重返 Google I/O 大会！立即报名。

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

زمانبندی استقرارها با استفاده از REST API همراه با cron job، می توانید محتوای میزبانی شده توسط Firebase را بر اساس یک برنامه منظم تغییر دهید (به عنوان مثال، برای استقرار یک نسخه ویژه تعطیلات یا رویداد مربوط به محتوای خود).
ادغام با ابزارهای توسعه دهنده می‌توانید در ابزار خود گزینه‌ای ایجاد کنید تا پروژه‌های برنامه وب خود را در میزبانی Firebase تنها با استفاده از یک کلیک (به عنوان مثال، کلیک کردن بر روی دکمه استقرار در یک IDE) اجرا کنید.
زمانی که محتوای استاتیک تولید می شود، به طور خودکار مستقر می شود. وقتی فرآیندی محتوای ثابت را به صورت برنامه‌نویسی تولید می‌کند (مثلاً محتوای تولید شده توسط کاربر مانند یک ویکی یا یک مقاله خبری)، شما می‌توانید محتوای تولید شده را به‌عنوان فایل‌های ثابت به‌جای ارائه‌ی پویا به آن‌ها گسترش دهید. این باعث صرفه جویی در توان محاسباتی گران قیمت می شود و فایل های شما را به روشی مقیاس پذیرتر ارائه می دهد.

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

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

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

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

صفحه Firebase Hosting API را در کنسول Google APIs باز کنید.
وقتی از شما خواسته شد، پروژه Firebase خود را انتخاب کنید.
توجه: هر پروژه Firebase دارای یک پروژه مربوطه در کنسول Google APIs است.
در صفحه Firebase Hosting API روی Enable کلیک کنید.

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

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

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

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

در کنسول Firebase، تنظیمات > حساب‌های سرویس را باز کنید.
روی Generate New Private Key کلیک کنید، سپس با کلیک روی Generate Key تأیید کنید.
فایل 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();
}

پس از انقضای نشانه دسترسی شما، روش بازخوانی نشانه به طور خودکار فراخوانی می شود تا یک نشانه دسترسی به روز شده بازیابی شود.

توجه: در حالی که استفاده از حساب سرویس برای کارهای خودکار در محیط های سرور مناسب است، راه های دیگری نیز برای دریافت مجوز برای استفاده از Firebase Hosting REST API وجود دارد. به عنوان مثال، اعضای پروژه می توانند از API استفاده کنند اگر (1) نقش مدیر یا ویرایشگر یک پروژه به آنها اختصاص داده شود و (2) نشانه های دسترسی را با محدوده مناسب ارائه دهند. سناریوهای دیگر را برای جریان‌های مختلف OAuth مرور کنید که به شما امکان می‌دهد مجوز استفاده از Firebase Hosting REST API را دریافت کنید.

مرحله 2: مطمئن شوید که پروژه شما دارای یک سایت میزبانی پیش فرض است

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

با تماس با نقطه پایانی 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" ، پروژه شما از قبل یک سایت میزبانی پیش‌فرض دارد. باقیمانده این مرحله را رد کنید و به مرحله بعدی بروید: یک نسخه جدید برای سایت خود ایجاد کنید .
- اگر یک آرایه خالی دریافت کردید، پس یک سایت میزبانی پیش فرض ندارید. باقی مانده این مرحله را کامل کنید.
در مورد SITE_ID برای سایت میزبانی پیش فرض خود تصمیم بگیرید. هنگام تصمیم گیری در مورد این SITE_ID موارد زیر را در نظر داشته باشید:
- این SITE_ID برای ایجاد زیر دامنه های Firebase پیش فرض شما استفاده می شود:
  SITE_ID .web.app و SITE_ID .firebaseapp.com .
- یک SITE_ID شرایط زیر را دارد:
  - باید یک برچسب نام میزبان معتبر باشد، به این معنی که نمی تواند حاوی . ، _ ، و غیره.
  - باید 30 کاراکتر یا کمتر باشد
  - باید در Firebase در سطح جهانی منحصر به فرد باشد
توجه داشته باشید که ما اغلب استفاده از شناسه پروژه خود را به عنوان SITE_ID برای سایت میزبانی پیش فرض خود توصیه می کنیم. با نحوه یافتن این شناسه در پروژه های Understand Firebase آشنا شوید.
سایت میزبانی پیش فرض خود را با فراخوانی 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"
}
```
اگر تصمیم دارید از شناسه پروژه خود به عنوان SITE_ID استفاده کنید، به موارد زیر توجه کنید:
در موارد نادر، شناسه پروژه شما قبلاً توسط پروژه دیگری برای ایجاد یک سایت میزبانی استفاده شده است. در این موارد، تماس با sites.create یک پیام خطای 400 برمی‌گرداند که می‌گوید SITE_ID ارائه‌شده reserved by another project شده است. برای رفع این خطا، با استفاده از رشته پیشنهادی در پیام خطا یا رشته دیگری تا زمانی که تماس با موفقیت انجام شود، دوباره با sites.create تماس بگیرید.

مرحله 3: یک نسخه جدید برای سایت خود ایجاد کنید

اولین تماس API شما ایجاد یک Version جدید برای سایت شما است. بعداً در این راهنما، فایل‌ها را در این نسخه آپلود می‌کنید، سپس آن را در سایت خود مستقر می‌کنید.

SITE_ID برای سایتی که می خواهید در آن مستقر شوید تعیین کنید.
توجه: برای سایت میزبانی پیش‌فرض شما، SITE_ID شناسه پروژه Firebase شما است (که برای ایجاد زیر دامنه‌های Firebase SITE_ID .web.app و SITE_ID .firebaseapp.com استفاده می‌شود).
اگر چندین سایت در پروژه Firebase خود ایجاد کرده‌اید، مطمئن شوید که از SITE_ID سایتی که می‌خواهید در آن مستقر شوید استفاده می‌کنید.

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

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

این API مستلزم آن است که فایل ها را با هش SHA256 شناسایی کنید. بنابراین، قبل از اینکه بتوانید فراخوانی API را انجام دهید، ابتدا باید یک هش برای هر فایل استاتیک را با Gziping کردن فایل ها محاسبه کنید و سپس هش SHA256 هر فایل تازه فشرده شده را بگیرید.

در ادامه مثال ما، فرض کنید که می خواهید سه فایل را در نسخه جدید مستقر کنید: file1 ، file2 و file3 .

Gzip فایل ها:
```
gzip file1 && gzip file2 && gzip file3
```
اکنون سه فایل فشرده file1.gz ، file2.gz و file3.gz دارید.

هش SHA256 هر فایل فشرده را دریافت کنید:

cat file1.gz | openssl dgst -sha256

66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4

cat file2.gz | openssl dgst -sha256

490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083

cat file3.gz | openssl dgst -sha256

59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315

اکنون سه هش SHA256 از سه فایل فشرده را دارید.

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

یک اسلش رو به جلو و هش فایل را به uploadUrl اضافه کنید تا یک URL خاص فایل در قالب ایجاد کنید: https://upload-firebasehosting.googleapis.com/upload/sites/ SITE_ID /versions/ VERSION_ID /files/ FILE_HASH .

همه فایل‌های مورد نیاز را یک به یک (در این مثال، فقط 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 شما قابل دسترسی هستند.

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