פריסה באתר באמצעות ה-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 בלחיצה אחת בלבד (לדוגמה, לחיצה על לחצן פריסה בתוך סביבת פיתוח משולבת).

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

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

  1. כדי לבדוק אם כבר מוגדר בפרויקט אתר Hosting שמוגדר כברירת מחדל, צריך להפעיל את נקודת הקצה sites.list.

    לדוגמה:

    פקודת cURLבקשת HTTPS גולמית
    curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \

https://firebasehosting.googleapis.com/v1beta1/projects/PROJECT_ID/sites

    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בקשת HTTPS גולמית
    curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \

https://firebasehosting.googleapis.com/v1beta1/projects/PROJECT_ID/sites?siteId=SITE_ID

    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בקשת HTTPS גולמית
    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

    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, תצטרכו קודם לחשב את הגיבוב (hash) של כל קובץ סטטי. לשם כך, עליכם לדחוס את הקבצים באמצעות Gzip ולאחר מכן לחשב את הגיבוב מסוג 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. שולחים את שלושת הגרסאות המקושרות (hash) האלה בבקשת API לנקודת הקצה versions.populateFiles. מציינים כל גיבוב לפי הנתיב הרצוי לקובץ שהועלו (בדוגמה הזו, /file1,‏ /file2 ו-/file3).

    לדוגמה:

    פקודת cURLבקשת HTTPS גולמית
    $ 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

    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, ולכן המחרוזת המקושרת שלה לא נכללת ברשימה uploadRequiredHashes.

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

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

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

צריך להעלות בנפרד כל קובץ נדרש (הקבצים שמפורטים ב-uploadRequiredHashes בתגובה versions.populateFiles בשלב הקודם). כדי להעלות את הקבצים האלה, תצטרכו את גיבובי ה-hash של הקבצים ואת הערך של 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בקשת HTTPS גולמית
    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

    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בקשת HTTPS גולמית
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

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בקשת HTTPS גולמית
curl -H "Authorization: Bearer ACCESS_TOKEN" \
       -X POST
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/releases?versionName=sites/SITE_ID/versions/VERSION_ID

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.