הגדרה וניהול של פרויקט 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 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 לנתיב של המפתח לחשבון השירות.

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

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

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 Console.

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

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

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

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

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

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 לכל אפליקציה קיימת ב-Firebase ל-Android באמצעות קריאה ל-projects.androidApps.sha.create. גוף הבקשה עבור הקריאה ל-method הזה חייב להכיל שדה name ריק. התוצאה של הקריאה הזו היא מכונה חדשה שנוצרה של ShaCertificate.

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

./gradlew signingReport

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

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

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

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

  • מציינים 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 נמחק באופן אוטומטי בסיום התהליך.