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

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

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

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

• הוספת שירותי Firebase לפרויקט
• הוספת אפליקציות Firebase לפרויקט Firebase
• קישור של פרויקט Firebase לחשבון Google Analytics

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

למידע על ניהול הרשאות גישה ל-Firebase Management API, קראו את מאמרי העזרה של Cloud Identity Access Management (IAM) API.

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

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

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

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

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

יצירת טוקן גישה ל-API

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

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

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

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

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

import { initializeApp, applicationDefault } from "firebase-admin/app";

initializeApp();

async function getAccessToken() {
  try {
    const accessToken = await applicationDefault().getAccessToken();
    return accessToken.access_token;
  } catch (err) {
    console.error('Unable to get access token');
    console.error(err);
  }
}

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

אפשר למצוא את הפרויקטים ב-Google Cloud שאפשר להוסיף להם שירותי Firebase.

בקשה

קוראים לפונקציה availableProjects.list. גוף הבקשה של הקריאה הזו חייב להיות ריק.

הנה דוגמה לבקשה של רשימת פרויקטים זמינים ב-Google Cloud באמצעות Node.js:

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. גוף הבקשה של הקריאה הזו חייב להיות ריק.

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

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.

{
  "displayName": "My Firebase iOS App",
  "bundleId": "com.firebase.ios"
}

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

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

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

{
  "name": "operations/...",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.IosApp",
    "name": "projects/first-cloud-project/iosApps/...",
    "appId": "...",
    "displayName": "My Firebase iOS App",
    "projectId": "first-cloud-project",
    "bundleId": "com.firebase.ios"
  }
}

{
  "displayName": "My Firebase Android App"
  "packageName": "com.firebase.android"
}

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

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

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

{
  "name": "operations/...",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.AndroidApp",
    "name": "projects/first-cloud-project/androidApps/...",
    "appId": "...",
    "displayName": "My Firebase Android App",
    "projectId": "first-cloud-project",
    "packageName": "com.firebase.android"
  }
}

./gradlew signingReport

{
  "displayName": "My Firebase Web App"
}

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

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

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

{
  "name": "operations/...",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.WebApp",
    "name": "projects/first-cloud-project/webApps/...",
    "appId": "...",
    "displayName": "My Firebase Web App",
    "projectId": "first-cloud-project"
  }
}

קישור של פרויקט Firebase לחשבון Google Analytics (אופציונלי)

אתם יכולים לקשר חשבון 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. בבדיקה הראשונה המערכת בודקת אם יש מקורות נתונים קיימים בנכס ב-Google Analytics שתואמים לאפליקציות Firebase קיימות ב-FirebaseProject (על סמך packageName או bundleId שמשויכים למקור הנתונים). לאחר מכן, מקורות הנתונים והאפליקציות מקושרים, בהתאם לצורך. חשוב לזכור שהקישור האוטומטי הזה חל רק על אפליקציות ל-Android ול-iOS.

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

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

בקשה

קוראים לפונקציה projects.addGoogleAnalytics.

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

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

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

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 הוא true והסוג של response הוא analyticsDetails, ה-FirebaseProject מקושר עכשיו לחשבון Google Analytics שצוין. ה-Operation נמחק אוטומטית בסיום.