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

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

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

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

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

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

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

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

מפעילים את Management REST API בפרויקט 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 לנתיב של המפתח לחשבון השירות.

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"

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

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

דוגמה ל-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.

אתם יכולים להוסיף אפליקציית Android ל-Firebase לפרויקט Firebase הקיים.

בקשה

קוראים לפונקציה projects.androidApps.create. כך יוצרים את גוף הבקשה:

  • נדרש:

    • packageName: שם החבילה הקנוני של אפליקציית Android כפי שהוא יופיע במסוף למפתחים של Google Play.

  • אופציונלי, אבל מומלץ:

    • displayName: שם התצוגה שהמשתמש הקצה לאפליקציה. הערך הזה שימושי כדי למצוא את האפליקציה מאוחר יותר במסוף Firebase.

בגוף הבקשה בדוגמה שלנו, נשתמש ב-packageName וב-displayName:

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

דוגמה ל-Node.js להוספת אפליקציית Firebase ל-Android לפרויקט Firebase:

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']);
  }
}

תוצאה

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

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

זהו תוכן התגובה של קריאה ל-operations.get:

{
  "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"
  }
}

מכיוון ש-done הוא true וסוג response הוא AndroidApp, עכשיו ל-FirebaseProject יש AndroidApp. התגובה מכילה גם מידע שימושי נוסף על אפליקציית Android של Firebase שיצרתם, כמו המזהה הייחודי של Firebase‏ appId. ה-Operation נמחק באופן אוטומטי בסיום.

הוספת אישורי SHA

אפשר להוסיף אישורי SHA לכל אפליקציית Android קיימת של Firebase באמצעות קריאה ל-projects.androidApps.sha.create. גוף הבקשה לקריאה ל-method הזה חייב לכלול שדה name ריק. התוצאה של הקריאה הזו היא מופע חדש של ShaCertificate.

כשקוראים ל-projects.androidApps.sha.create, צריך לספק גיבוב (hash) תקין של אישור SHA-1 או SHA-256. אפשר לקבל את גיבוב ה-SHA של אישור החתימה באמצעות הפקודה signingReport של gradle: 

./gradlew signingReport

מידע נוסף זמין במאמר Google APIs ל-Android.

אפשר לקשר חשבון 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.

מידע נוסף על ההיררכיה והמבנה של חשבונות 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 נמחק באופן אוטומטי בסיום.