הגדרה וניהול של פרויקט Firebase באמצעות ה-Management API בארכיטקטורת REST

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

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

תוכלו לדלג לחלקים ספציפיים בדף הזה אם אתם רק רוצים:

לפני שמבצעים שלבים כלשהם בדף הזה, צריך לוודא להפעיל את ה-API.

למידע על ניהול הרשאות גישה ל-Firebase Management API, אפשר לבקר בכתובת ממשק ה-API של Cloud Identity Access Management תיעוד.

לפני שמתחילים

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

הפעלת ה-Management API ל-REST בפרויקט Google Cloud שלך

אם עדיין לא עשית זאת, עליך להפעיל את ניהול Firebase API לשימוש בפרויקט Google Cloud.

  1. פותחים את ניהול Firebase API במסוף Google APIs.
  2. כשמופיעה בקשה, בוחרים את הפרויקט Google Cloud.
  3. לוחצים על Enable בדף Firebase Management API.

יצירת אסימון הגישה ל-API

בהמשך מוצגת דוגמה ל-Node.js שמאחזר את אסימון הגישה.

קודם כול, אם אתם לא בסביבת Google Cloud, מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS לנתיב של המפתח לחשבון השירות.

Linux או macOS

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"

Windows

באמצעות PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\service-account-file.json"

לאחר מכן, עליך להשתמש ב-SDK Admin של Firebase כדי לקבל אסימון גישה מהשירות שלך פרטי הכניסה של החשבון:

const admin = require('firebase-admin');

function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}

איתור שם המשאב של הפרויקט

כאן אפשר למצוא את Google Cloud הפרויקטים שזמינים להוספת Firebase שירותים שונים.

בקשה

שיחת טלפון availableProjects.list גוף הבקשה לשיחה הזו חייב להיות ריק.

דוגמה: Node.js יכול לבקש רשימה של Google Cloud זמינים פרויקטים:

const fetch = require('node-fetch');

async function listProjects() {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/availableProjects';
  const options = {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    const projects = resp['projectInfo'];
    console.log('Project total: ' + projects.length);
    console.log('');
    for (let i in projects) {
      const project = projects[i];
      console.log('Project ' + i);
      console.log('ID: ' + project['project']);
      console.log('Display Name: ' + project['displayName']);
      console.log('');
    }
  } catch(err) {
    console.error(err);
  }
}

תוצאה

גוף התשובה מהקריאה ל-availableProjects.list מכיל רשימה של אובייקטים מסוג ProjectInfo. אם רשימת הפרויקטים ארוכה מדי, גוף התשובה יכלול גם nextPageToken, שאפשר להשתמש בו כפרמטר של שאילתה כדי לקבל את הדף הבא של פרויקטים.

דוגמה לגוף תשובה לקריאה של availableProjects.list:

{
  "projectInfo": [
    {
      "project": "projects/first-cloud-project",
      "displayName": "First Cloud Project"
    },
    {
      "project": "projects/second-cloud-project",
      "displayName": "Second Cloud Project"
    }
  ]
}

התשובה בדוגמה הזו כוללת שני פרויקטים של Google Cloud שיכולים להיות להם Firebase השירותים שנוספו אליהם. חשוב לשים לב שהשדה project מספק את הערכים הגלובליים שם משאב ייחודי לפרויקט.

אפשר להשתמש בכל ערך של project שרשום בתשובה של availableProjects.list כדי להוסיף שירותי Firebase או מוסיפים אפליקציות לפרויקט.

בקטע הבא נוסיף את שירותי Firebase אל First Cloud Project באמצעות שם המשאב projects/first-gcp-project.

הוספת שירותי Firebase לפרויקט

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

בקשה

שיחת טלפון projects.addFirebase גוף הבקשה לשיחה הזו חייב להיות ריק.

דוגמה להוספה של שירותי Firebase ל-Node.js ל-Google Cloud project:

const fetch = require('node-fetch');

async function addFirebase(projectId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + ':addFirebase';
  const options = {
    method: 'POST',
    // Use a manual access token here since explicit user access token is required.
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

תוצאה

התוצאה של שיחה אל projects.addFirebase היא Operation. לפני שמתחילים יכולה לקרוא לנקודות קצה אחרות שקשורות ל-Firebase בשביל הפרויקט, הפעולה חייבת להצליח.

כדי לבדוק אם הפעולה הצליחה, אפשר להתקשר operations.get בפעולה עד שהערך של done הוא true ו-response שלו הוא מקלידים FirebaseProject. אם הפעולה נכשלת, error שלה מוגדר לערך google.rpc.Status.

זה גוף התשובה בשיחת operations.get:

{
  "name": "operations/...",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.FirebaseProject",
    "projectId": "first-cloud-project",
    "projectNumber": "...",
    "displayName": "First Cloud Project",
    "name": "projects/first-cloud-project",
    "resources": {
      "hostingSite": "first-cloud-project",
      "realtimeDatabaseInstance": "first-cloud-project"
    }
  }
}

מכיוון ש-done הוא true והסוג response הוא FirebaseProject, לפרויקט Google Cloud יש עכשיו שירותים של Firebase. התשובה מכילה גם מידע שימושי אחר על FirebaseProject החדש שיצרת, כמו projectNumber וברירת המחדל שלו resources. ה-Operation נמחק באופן אוטומטי בסיום.

הוספה של אפליקציות Firebase לפרויקט

אפשר להשתמש בFirebaseProject באפליקציות שונות, כולל iOS, Android ואפליקציות אינטרנט תרגום מכונה. בקטע הזה נסביר איך להוסיף אפליקציות Firebase לחשבון קיים FirebaseProject באופן פרוגרמטי. לתשומת ליבכם: אפשר גם להוסיף אפליקציות של Firebase לפרויקט Firebase הקיים במסוף Firebase.

בוחרים את סוג האפליקציה ב-Firebase שרוצים להוסיף לפרויקט ב-Firebase.

אפשר לקשר חשבון קיים חשבון Google Analytics לחשבון הקיים FirebaseProject באופן פרוגרמטי. לתשומת ליבכם: אפשר גם לקשר את הפרויקט הקיים ב-Firebase ל-Google Analytics בכרטיסייה Integrations (שילובים) בקטע Project Settings (הגדרות הפרויקט).

הקריאה אל projects.addGoogleAnalytics מחייבת analytics_resource, שיכול להיות analyticsAccountId או analyticsPropertyId:

  • יש לציין analyticsAccountId קיים כדי להקצות חשבון Google Analytics חדש בחשבון שצוין ולשייך את הנכס החדש אל פרויקט Firebase.

  • ציון analyticsPropertyId קיים כדי לשייך את Google Analytics נכס עם פרויקט Firebase שלכם.

אפשר למצוא את analyticsAccountId ואת כל analyticsPropertyId הקיימים באתר של Google Analytics.

כשמתקשרים ל-projects.addGoogleAnalytics:

  1. הבדיקה הראשונה קובעת אם יש מקורות נתונים קיימים נכס Analytics תואם לאפליקציות קיימות ב-Firebase FirebaseProject (על סמך packageName או bundleId שמשויכים אל מקור הנתונים). לאחר מכן, אם זה רלוונטי, מקורות הנתונים והאפליקציות מקושרים. לתשומת ליבכם: הקישור האוטומטי הזה רלוונטי רק לאפליקציות ל-Android ול-iOS.

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

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

בקשה

שיחת טלפון projects.addGoogleAnalytics

בגוף הבקשה של קריאת הדוגמה שלנו ל-project.addGoogleAnalytics, נספק את חשבון Google Analytics שלנו, analyticsAccountId. הקריאה הזו תקצה נכס Google Analytics חדש ותשייך את הנכס החדש ל-FirebaseProject.

{
  "analyticsAccountId": "<your-google-analytics-account-id>"
}

דוגמה: Node.js לקשר פרויקט Firebase ל-Google Analytics חשבון:

const fetch = require('node-fetch');

async function addGoogleAnalytics(projectId, analyticsAccountId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + ':addGoogleAnalytics';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'analyticsAccountId': analyticsAccountId
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

תוצאה

התוצאה של שיחה אל projects.addGoogleAnalytics היא Operation. לפני שמתחילים יכולה לקרוא לנקודות קצה אחרות שקשורות ל-Firebase בשביל הפרויקט, הפעולה חייבת להצליח.

כדי לבדוק אם הפעולה בוצעה בהצלחה, אפשר להפעיל את operations.get על הפעולה עד שהערך של done יהיה true ו-response יהיה מסוג analyticsDetails. אם הפעולה נכשלת, error שלה מוגדר לערך google.rpc.Status.

זה גוף התשובה בשיחת operations.get:

{
  "name": "operations/...",
  "none": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.AnalyticsDetails",
    "analyticsProperty": [
      {
        "id": "...",
        "displayName": "..."
      }
    ],
    "streamMappings": [
      {
        "app": "...",
        "streamId": "...",
        "measurementId": "..."
      }
    ]
  }
}

מכיוון ש-done נכון והסוג של response הוא analyticsDetails, עכשיו FirebaseProject מקושר לחשבון Google Analytics שצוין. Operation נמחק באופן אוטומטי בסיום הפעולה.

השלמת מיקום ברירת המחדל של הפרויקט (אופציונלי)

אם בפרויקט Firebase נעשה שימוש ב-Cloud Firestore, ב-Cloud Storage, או אפליקציה App Engine, אפשר להשלים את ברירת המחדל של Google Cloud מיקום המשאב של הפלטפורמה (GCP) בפרויקט באופן פרוגרמטי. לתשומת ליבך: אפשר גם לבחור מיקום ב- ה מסוף Firebase.

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

קריאה לשיטה הזו של defaultLocation.finalize יוצרת App Engine אפליקציה עם ברירת מחדל ל-Cloud Storage קטגוריה שנמצאים ב locationId שאתם מציינים בגוף הבקשה.

ייתכן שמיקום ברירת המחדל של משאב GCP כבר צוין אם ב-Project כבר יש אפליקציה של App Engine, או בוצעה קריאה בעבר ל-method defaultLocation.finalize.

בקשה

שיחת טלפון projects.defaultLocation.finalize כך יוצרים את גוף הבקשה:

  • נדרש:

    • locationId: המיקום שבו מאוחסנים הנתונים עבור שירותי GCP שמצריכות הגדרת מיקום, כמו Cloud Firestore Cloud Storage.
{
  "locationId": "us-west2"
}

הנה דוגמה ש-Node.js יכול לאשר כדי לסיים את מיקום ברירת המחדל של הפרויקט:

const fetch = require('node-fetch');

async function finalizeProjectLocation(projectId, locationId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + '/defaultLocation:finalize';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'locationId': locationId
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

תוצאה

התוצאה של שיחה אל projects.defaultLocation.finalize היא Operation. כדי שתוכלו לבצע קריאה לנקודות קצה אחרות שקשורות ל-Firebase בפרויקט, הפעולה צריכה להצליח.

כדי לבדוק אם הפעולה הצליחה, אפשר להתקשר אל operations.get עד שהערך של done יהיה true והresponse הוא מסוג google.protobuf.Empty אם הפעולה נכשלת, גוף התגובה error יהיה מסוג google.rpc.Status. Operation מופעל באופן אוטומטי נמחק אחרי השלמתו.