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

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

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

לדוגמה, באמצעות Firebase Hosting API בארכיטקטורת REST, אתם יכולים:

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

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

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

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

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

לפני שמתחילים: הפעלת ה-API בארכיטקטורת REST

צריך להפעיל את Firebase Hosting API בארכיטקטורת REST ב-Google APIs Console:

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

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

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

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

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

אפשר לראות את כל חשבונות השירות של פרויקט Firebase בכרטיסייה Settings (הגדרות) > Service accounts (חשבונות שירות).

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

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

  1. במסוף Firebase, עוברים אל הגדרות > הכרטיסייה חשבונות שירות.

  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, בפרויקט Firebase צריך להיות Hosting SITE שמוגדר כברירת מחדל.

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

  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, תצטרכו קודם לחשב גיבוב לכל קובץ סטטי. לשם כך, תצטרכו לבצע 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. שולחים את שלושת הגיבובים האלה בבקשת 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.

שולחים קריאה לנקודת הקצה 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.