פריסה באתר באמצעות ה-API ל-REST של אירוח

Firebase Hosting REST API מאפשר פריסות פרוגרמטיות ומותאמות אישית לאתרים שמתארחים ב-Firebase. משתמשים ב-API ל-REST כדי לפרוס תוכן והגדרות אישיות חדשים או מעודכנים של Hosting.

במקום להשתמש ב-CLI של Firebase לפריסות, אפשר להשתמש ב-API ל-REST של Firebase Hosting כדי ליצור באופן פרוגרמטי version חדש של נכסים לאתר, להעלות קבצים לגרסה ואז לפרוס את הגרסה באתר.

לדוגמה, באמצעות ה-API ל-REST של Firebase Hosting אפשר:

  • תזמון פריסות באמצעות ה-API ל-REST בשילוב עם משימה של cron, תוכלו לשנות תוכן שמתארח ב-Firebase במסגרת לוח זמנים קבוע (לדוגמה, כדי לפרוס גרסה מיוחדת של התוכן שקשורה לחג או לאירוע).

  • שילוב עם כלים למפתחים אפשר ליצור בכלי אפשרות לפרוס פרויקטים של אפליקציות אינטרנט ב-Firebase Hosting בלחיצה אחת (לדוגמה, לחיצה על לחצן פריסה בתוך סביבת פיתוח משולבת (IDE).

  • פריסה אוטומטית כשנוצר תוכן סטטי כשתהליך יוצר תוכן סטטי באופן פרוגרמטי (לדוגמה, תוכן שנוצר על ידי משתמשים, כמו וויקי או מאמר חדשותי), אפשר לפרוס את התוכן שנוצר כקבצים סטטיים במקום להציג אותו באופן דינמי. כך חוסכים בצריכת מחשוב יקרה ומשרתים את הקבצים באופן שניתן להתאמה.

במדריך הזה נסביר קודם איך מפעילים, מאמתים ומעניקים הרשאה ל-API. לאחר מכן, במדריך הזה נספק דוגמה ליצירת גרסה של Firebase Hosting, להעלאת הקבצים הנדרשים לגרסה ולפריסה שלה.

מידע נוסף על ה-API הזה ל-REST מופיע גם בחומרי העזר המלאים Hosting של API ל-REST.

לפני שמתחילים: צריך להפעיל את ה-API ל-REST

צריך להפעיל את ה-API ל-REST של Firebase Hosting במסוף Google APIs:

  1. פותחים את דף ה-API של Firebase Hosting במסוף Google APIs.

  2. כשמוצגת בקשה, בוחרים את פרויקט Firebase.

  3. לוחצים על Enable בדף ה-API של Firebase Hosting.

שלב 1: קבלת אסימון גישה לאימות ולאישור בקשות API

פרויקטים ב-Firebase תומכים בחשבונות שירות של Google, שבאמצעותם אפשר לבצע קריאה ל-API של שרת Firebase משרת האפליקציה או מסביבה מהימנה. אם אתם מפתחים קוד באופן מקומי או פורסים את האפליקציה בארגון, תוכלו להשתמש בפרטי הכניסה שהתקבלו דרך חשבון השירות הזה כדי לאשר בקשות מהשרת.

כדי לאמת חשבון שירות ולהעניק לו הרשאת גישה לשירותי Firebase, צריך ליצור קובץ מפתח פרטי בפורמט JSON.

כדי ליצור קובץ מפתח פרטי לחשבון השירות:

  1. במסוף Firebase, פותחים את Settings (הגדרות) > Service Accounts (חשבונות שירות).

  2. לוחצים על Generate New Private Key (יצירת מפתח פרטי חדש) ואז על Generate Key (יצירת מפתח) כדי לאשר.

  3. מאחסנים באופן מאובטח את קובץ ה-JSON שמכיל את המפתח.

משתמשים בפרטי הכניסה ל-Firebase יחד עם ספריית האימות של Google בשפה המועדפת עליכם כדי לאחזר אסימון גישה לטווח קצר מסוג 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.

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();
}

אחרי שתוקף אסימון הגישה יפוג, השיטה לרענון האסימון תופעל באופן אוטומטי כדי לאחזר אסימון גישה מעודכן.

שלב 2: מוודאים שלפרויקט יש אתר Hosting שמוגדר כברירת מחדל

לפני הפריסה הראשונה ב-Firebase Hosting, צריך להגדיר פרמטר ברירת מחדל של Hosting SITE לפרויקט ב-Firebase.

  1. כדי לבדוק אם בפרויקט שלכם כבר יש אתר ברירת מחדל של Hosting, מפעילים את נקודת הקצה (endpoint) 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

    קריאת ה-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

    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 יש מגבלת גודל של 2GB לקבצים בודדים.

ב-API הזה צריך לזהות קבצים לפי גיבוב SHA256. לכן, כדי להפעיל את הקריאה ל-API, צריך קודם לחשב את הגיבוב לכל קובץ סטטי באמצעות Gzipping את הקבצים, ולאחר מכן לבצע את הגיבוב 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"
}

התשובה הזו כוללת:

  • ה-hash של כל קובץ שצריך להעלות. לדוגמה, בדוגמה הזו כבר הועלתה גרסה קודמת של file1, ולכן המחרוזת המקושרת (hash) שלה לא נכללת ברשימה uploadRequiredHashes.

  • uploadUrl שספציפי לגרסה החדשה.

בשלב הבא, כדי להעלות את שני הקבצים החדשים, תצטרכו את הגיבובים ואת הערך של uploadURL מהתגובה versions.populateFiles.

שלב 5: העלאת הקבצים הנדרשים

צריך להעלות בנפרד כל קובץ נדרש (הקבצים שמפורטים ב-uploadRequiredHashes מהתשובה versions.populateFiles בשלב הקודם). כדי להעלות את הקבצים האלה, צריך את הגיבובים של הקבצים ואת uploadUrl מהשלב הקודם.

  1. מוסיפים קו נטוי קדימה ואת ה-hash של הקובץ ל-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 בבקשת ה-API מוגדר ל-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"}

הקריאה הזו ל-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.