Firebase Hosting REST API מאפשר פריסות מותאמות אישית באתרים שמארחים ב-Firebase, באמצעות תכנות. אפשר להשתמש ב-REST API הזה כדי לפרוס תוכן חדש או מעודכן Hosting והגדרות.
במקום להשתמש ב-Firebase CLI לפריסות, אפשר להשתמש ב-Firebase Hosting REST API כדי ליצור באופן פרוגרמטי version חדש של נכסים לאתר, להעלות קבצים לגרסה ואז לפרוס את הגרסה באתר.
לדוגמה, באמצעות Firebase Hosting REST API, אתם יכולים:
תזמון פריסות באמצעות REST API בשילוב עם משימת cron, אתם יכולים לשנות את התוכן שמתארח ב-Firebase בלוח זמנים קבוע (לדוגמה, כדי לפרוס גרסה מיוחדת של התוכן שקשורה לחג או לאירוע).
שילוב עם כלים למפתחים אתם יכולים ליצור בכלי שלכם אפשרות לפריסת פרויקטים של אפליקציות אינטרנט ב-Firebase Hosting בלחיצה אחת בלבד (לדוגמה, לחיצה על לחצן פריסה בסביבת פיתוח משולבת).
אוטומציה של פריסות כשנוצר תוכן סטטי. כשבתהליך מסוים נוצר תוכן סטטי באופן פרוגרמטי (למשל תוכן שנוצר על ידי משתמשים, כמו מאמר בוויקי או מאמר חדשותי), אפשר לפרוס את התוכן שנוצר כקובצים סטטיים במקום להציג אותו באופן דינמי. כך תוכלו לחסוך בעלויות של כוח מחשוב ולספק את הקבצים בצורה ניתנת יותר להרחבה.
במדריך הזה מוסבר קודם איך להפעיל את ה-API, לאמת אותו ולתת לו הרשאה. בהמשך המדריך מופיעה דוגמה ליצירת Firebase Hostingגרסה, להעלאת הקבצים הנדרשים לגרסה ולפריסת הגרסה.
מידע נוסף על ה-API ל-REST הזה זמין גם במסמכי העיון המלאים של Hosting API ל-REST.
לפני שמתחילים: הפעלת ה-API ל-REST
צריך להפעיל את Firebase Hosting REST API ב-Google APIs Console:
פותחים את הדף Firebase Hosting API במסוף Google APIs.
כשמתבקשים, בוחרים את הפרויקט ב-Firebase.
לוחצים על הפעלה בדף של Firebase Hosting API.
שלב 1: מקבלים אסימון גישה לאימות ולהרשאה של בקשות ל-API
פרויקטים ב-Firebase תומכים בחשבונות שירות של Google, שאפשר להשתמש בהם כדי לקרוא ל-Firebase Server APIs משרת האפליקציות או מסביבה מהימנה. אם אתם מפתחים קוד באופן מקומי או פורסים את האפליקציה שלכם בשרת מקומי, אתם יכולים להשתמש בפרטי הכניסה שהתקבלו דרך חשבון השירות הזה כדי לאשר בקשות לשרת.
כדי לאמת חשבון שירות ולאשר לו גישה לשירותי Firebase, צריך ליצור קובץ מפתח פרטי בפורמט JSON.
כדי ליצור קובץ מפתח פרטי לחשבון השירות:
במסוף Firebase, פותחים את Settings > Service Accounts.
לוחצים על Generate New Private Key (יצירת מפתח פרטי חדש) ואז על Generate Key (יצירת מפתח) כדי לאשר.
מאחסנים את קובץ ה-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 שמוגדר כברירת מחדל.
כדי לבדוק אם כבר יש לפרויקט אתר ברירת מחדל, מתקשרים לנקודת הקצה
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. משלימים את שאר השלבים.
מחליטים על
SITE_IDלאתר ברירת המחדל Hosting. כשבוחרים אתSITE_ID, חשוב לזכור את הנקודות הבאות:ה-
SITE_IDהזה משמש ליצירת תתי-הדומיינים שלכם ב-Firebase שמוגדרים כברירת מחדל:
SITE_ID.web.appSITE_ID.firebaseapp.comהדרישות בנוגע ל-
SITE_ID:- צריך להזין כאן תווית שם מארח תקינה, כלומר היא לא יכולה להכיל את התווים
.,_וכו'. - האורך המקסימלי הוא 30 תווים
- חייב להיות ייחודי בהיקף גלובלי ב-Firebase
- צריך להזין כאן תווית שם מארח תקינה, כלומר היא לא יכולה להכיל את התווים
שימו לב: אנחנו ממליצים לעיתים קרובות להשתמש במזהה הפרויקט כ
SITE_IDבאתר ברירת המחדל Hosting. איך מוצאים את המזהה הזהכדי ליצור את אתר ברירת המחדל של 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 חדש לאתר.
בהמשך המדריך הזה, תעלו קבצים לגרסה הזו ואז תפרסו אותה באתר.
קובעים את SITE_ID של האתר שבו רוצים להטמיע את התכונה.
מתקשרים לנקודת הקצה 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.
מכווצים את הקבצים בפורמט 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: העלאת הקבצים הנדרשים
צריך להעלות כל קובץ בנפרד (הקבצים שמופיעים בתגובה versions.populateFiles בשלב הקודם, uploadRequiredHashes). כדי להעלות את הקבצים האלה, תצטרכו את הגיבובים של הקבצים ואת 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.
שולחים קריאה לנקודת הקצה 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/file1https://SITE_ID.web.app/file2https://SITE_ID.web.app/file3
אפשר לגשת לקבצים האלה גם בכתובות URL שמשויכות לדומיין SITE_ID.firebaseapp.com.
אפשר לראות את הגרסה החדשה גם בלוח הבקרה של Hosting במסוף Firebase.