Das Firebase Admin SDK ist eine Reihe von Serverbibliotheken, mit denen Sie von privilegierten Umgebungen aus mit Firebase interagieren können, um Aktionen wie Abfragen und Mutationen für einen Firebase SQL Connect-Dienst für die Massendatenverwaltung und andere Vorgänge mit erhöhten Berechtigungen und imitierten Anmeldedaten auszuführen.
Die Admin SDK bietet eine API, mit der Sie Vorgänge sowohl im Lese-/Schreibmodus als auch im Lesemodus aufrufen können. Mit den schreibgeschützten Vorgängen können Sie Verwaltungsfunktionen implementieren, die keine Daten in Ihren Datenbanken ändern können.
Admin SDK einrichten
Wenn Sie Firebase SQL Connect auf Ihrem Server verwenden möchten, müssen Sie zuerst das Admin SDK für Node.js installieren und einrichten.
Admin SDK in Ihren Skripts initialisieren
Importieren Sie zum Initialisieren des SDK die SQL Connect-Erweiterungen und deklarieren Sie die Dienst-ID und den Standort Ihres Projekts.
import { initializeApp } from 'firebase-admin/app';
import { getDataConnect } from 'firebase-admin/data-connect';
// If you'd like to use OAuth2 flows and other credentials to log in,
// visit https://firebase.google.com/docs/admin/setup#initialize-sdk
// for alternative ways to initialize the SDK.
const app = initializeApp();
const dataConnect = getDataConnect({
serviceId: 'serviceId',
location: 'us-west2'
});
Abfragen und Mutationen für die Verwendung mit der Admin SDK entwerfen
Admin SDK ist nützlich, um SQL Connect-Vorgänge auszuführen, wenn Sie Folgendes beachten.
SDK und @auth(level: NO_ACCESS)-Vorgangsanweisung verstehen
Da der Admin SDK mit Berechtigungen arbeitet, kann er alle Ihre Abfragen und Mutationen unabhängig von den Zugriffsebenen ausführen, die mit @auth-Anweisungen festgelegt wurden, einschließlich der Ebene NO_ACCESS.
Wenn Sie neben Ihren Clientvorgängen Ihre administrativen Abfragen und Mutationen in .gql-Quelldateien organisieren, um sie in administrative Skripts zu importieren, empfiehlt Firebase, die administrativen Vorgänge ohne Autorisierungszugriffsebene zu kennzeichnen oder sie explizit als NO_ACCESS festzulegen. In beiden Fällen wird verhindert, dass solche Vorgänge von Clients oder in anderen nicht privilegierten Kontexten ausgeführt werden.
SDK mit dem SQL Connect-Emulator verwenden
In Prototyp- und Testumgebungen kann es nützlich sein, Daten-Seeding und andere Vorgänge für lokale Daten auszuführen. Mit Admin SDK können Sie Ihre Workflows vereinfachen, da die Authentifizierung und Autorisierung für lokale Abläufe ignoriert werden können. (Sie können sich auch explizit dafür entscheiden, die Authentifizierungs- und Autorisierungskonfiguration Ihrer Vorgänge mit dem Wechsel der Nutzeridentität einzuhalten.)
Die Firebase Admin SDKs stellen automatisch eine Verbindung zum SQL Connect-Emulator her, wenn die Umgebungsvariable DATA_CONNECT_EMULATOR_HOST festgelegt ist:
export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"
Weitere Informationen finden Sie unter:
Administratorvorgänge ausführen
Admin SDK wird für privilegierte Vorgänge für Ihre kritischen Daten bereitgestellt.
Das Admin SDK bietet drei API-Sets:
- Generierte Admin SDKs, die typsichere SDKs sind und aus Ihren
gql-Definitionen auf die gleiche Weise generiert werden wie Client SDKs. - Eine allgemeine Schnittstelle zum Ausführen beliebiger GraphQL-Vorgänge, bei der Ihr Code Abfragen und Mutationen implementiert und an die Lese-/Schreibmethode
executeGraphqloder die Methode mit LesezugriffexecuteGraphqlReadübergibt. - Eine spezielle Schnittstelle für Bulk-Datenvorgänge, die anstelle von generischen
executeGraphql-Methoden dedizierte Methoden für Mutationsvorgänge bereitstellt:insert,insertMany,upsertundupsertMany.
Daten mit generierten SDKs verwalten
Sie generieren Admin-SDKs aus Ihren gql-Definitionen auf dieselbe Weise wie Client-SDKs.
Das generierte Admin SDK enthält Schnittstellen und Funktionen, die Ihren gql-Definitionen entsprechen und mit denen Sie Vorgänge in Ihrer Datenbank ausführen können. Angenommen, Sie haben ein SDK für eine Datenbank mit Songs und die Abfrage getSongs generiert:
import { initializeApp } from "firebase-admin/app";
import { getSongs } from "@dataconnect/admin-generated";
const adminApp = initializeApp();
const songs = await getSongs(
{ limit: 4 },
{ impersonate: { unauthenticated: true } }
);
Alternativ können Sie eine Connector-Konfiguration angeben:
import { initializeApp } from "firebase-admin/app";
import { getDataConnect } from "firebase-admin/data-connect";
import {
connectorConfig,
getSongs,
} from "@dataconnect/admin-generated";
const adminApp = initializeApp();
const adminDc = getDataConnect(connectorConfig);
const songs = await getSongs(
adminDc,
{ limit: 4 },
{ impersonate: { unauthenticated: true } }
);
Identitätsdiebstahl eines nicht authentifizierten Nutzers
Admin SDKs sind für die Ausführung in vertrauenswürdigen Umgebungen vorgesehen und haben daher uneingeschränkten Zugriff auf Ihre Datenbanken.
Wenn Sie öffentliche Vorgänge mit dem Admin SDK ausführen, sollten Sie den Vorgang nicht mit vollständigen Administratorberechtigungen ausführen (gemäß dem Prinzip der geringsten Berechtigung). Stattdessen sollten Sie den Vorgang entweder als Nutzer, dessen Identität angenommen wurde (siehe nächster Abschnitt), oder als nicht authentifizierter Nutzer, dessen Identität angenommen wurde, ausführen.
Nicht authentifizierte Nutzer können nur Vorgänge ausführen, die als PUBLIC gekennzeichnet sind.
Im obigen Beispiel wird die Abfrage getSongs als nicht authentifizierter Nutzer ausgeführt.
Übernahme der Nutzeridentität
Sie können auch Vorgänge im Namen bestimmter Nutzer ausführen, indem Sie einen Teil oder das gesamte Firebase Authentication-Token in der Option impersonate übergeben. Sie müssen mindestens die Nutzer-ID des Nutzers im Unteranspruch angeben. (Dies ist derselbe Wert wie der auth.uid-Serverwert, auf den Sie in SQL Connect-GraphQL-Vorgängen verweisen können.)
Wenn Sie die Identität eines Nutzers übernehmen, ist der Vorgang nur erfolgreich, wenn die von Ihnen angegebenen Nutzerdaten die in Ihrer GraphQL-Definition angegebenen Authentifizierungsprüfungen bestehen.
Wenn Sie das generierte SDK von einem öffentlich zugänglichen Endpunkt aus aufrufen, ist es wichtig, dass der Endpunkt eine Authentifizierung erfordert und dass Sie die Integrität des Authentifizierungstokens validieren, bevor Sie es verwenden, um die Identität eines Nutzers anzunehmen.
Wenn Sie aufrufbare Cloud Functions verwenden, wird das Authentifizierungstoken automatisch überprüft und Sie können es wie im folgenden Beispiel verwenden:
import { HttpsError, onCall } from "firebase-functions/https";
export const callableExample = onCall(async (req) => {
const authClaims = req.auth?.token;
if (!authClaims) {
throw new HttpsError("unauthenticated", "Unauthorized");
}
const favoriteSongs = await getMyFavoriteSongs(
undefined,
{ impersonate: { authClaims } }
);
// ...
});
Andernfalls verwenden Sie die Methode verifyIdToken von Admin SDK, um das Authentifizierungstoken zu validieren und zu decodieren. Angenommen, Ihr Endpunkt ist als einfache HTTP-Funktion implementiert und Sie haben das Firebase Authentication-Token wie üblich mit dem authorization-Header an Ihren Endpunkt übergeben:
import { getAuth } from "firebase-admin/auth";
import { onRequest } from "firebase-functions/https";
const auth = getAuth();
export const httpExample = onRequest(async (req, res) => {
const token = req.header("authorization")?.replace(/^bearer\s+/i, "");
if (!token) {
res.sendStatus(401);
return;
}
let authClaims;
try {
authClaims = await auth.verifyIdToken(token);
} catch {
res.sendStatus(401);
return;
}
const favoriteSongs = await getMyFavoriteSongs(
undefined,
{ impersonate: { authClaims } }
);
// ...
});
Nur wenn Sie echte administrative Aufgaben wie die Datenmigration aus einer sicheren, nicht öffentlich zugänglichen Umgebung ausführen, sollten Sie eine Nutzer-ID angeben, die nicht aus einer überprüfbaren Quelle stammt:
// Never do this if end users can initiate execution of the code!
const favoriteSongs = await getMyFavoriteSongs(
undefined,
{ impersonate: { authClaims } }
);
Wird mit uneingeschränktem Zugriff ausgeführt
Wenn Sie einen Vorgang ausführen, für den Berechtigungen auf Administratorebene erforderlich sind, lassen Sie den Parameter „impersonate“ im Aufruf weg:
await upsertSong(adminDc, {
title: songTitle_one,
instrumentsUsed: [Instrument.VOCAL],
});
Ein auf diese Weise aufgerufener Vorgang hat vollständigen Zugriff auf die Datenbank. Wenn Sie Abfragen oder Mutationen haben, die nur für Verwaltungszwecke verwendet werden sollen, sollten Sie sie mit der Anweisung @auth(level: NO_ACCESS) definieren. Dadurch wird sichergestellt, dass nur Aufrufer auf Administratorebene diese Vorgänge ausführen können.
Daten mit executeGraphql-Methoden verwalten
Wenn Sie einmalige Vorgänge ausführen müssen, für die Sie keine gql-Mutationen oder -Abfragen definiert haben, können Sie die Methode executeGraphql oder die schreibgeschützte Methode executeGraphqlRead verwenden.
Benutzerdefinierte verschachtelte relationale Vorgänge (1:n- und 1:1-Beziehungen) mit executeGraphql ausführen
Wenn Sie Vorgänge aus dem Admin SDK in einer privilegierten Umgebung aufrufen, müssen Sie die Anweisung @allow für Ihre Variablen für standardmäßige flache (nicht verschachtelte) Einfügungen (z. B. Einfügen einzelner Film- oder Schauspielerdatensätze) nicht angeben.
Bei verschachtelten relationalen Einfügungen (z. B. Einfügen eines Films zusammen mit seinen ersten Rezensionen oder eines Nutzers und seines Profils) müssen Sie jedoch weiterhin die Anweisung @allow in Ihrer Variablendefinition deklarieren, um die verschachtelten relationalen Felder im kompilierten Variablenschema statisch zuzulassen.
// Custom GraphQL mutation with nested relational insert (one-to-many)
const customMutation = `
mutation CustomBatchInsert(
$data: [Movie_Data!]!
@allow(fields: "title genre reviews_on_movie { rating reviewText }")
) {
movie_insertMany(data: $data)
}
`;
const variables = {
data: [
{
title: "Interstellar",
genre: "Sci-Fi",
reviews_on_movie: [
{
rating: 5,
reviewText: "Visually stunning and emotionally powerful.",
user: { id: "user-789" }
}
]
}
]
};
const response = await dataConnect.executeGraphql(customMutation, { variables });
// Custom GraphQL mutation with a one-to-one nested relational insert
const customMutationOneToOne = `
mutation CustomBatchInsertOneToOne(
$data: [User_Data!]!
@allow(fields: "name profile_on_user { bio }")
) {
user_insertMany(data: $data)
}
`;
const variablesOneToOne = {
data: [
{
name: "Alice",
profile_on_user: {
bio: "Avid moviegoer and critic."
}
}
]
};
const responseOneToOne = await dataConnect.executeGraphql(customMutationOneToOne, { variables: variablesOneToOne });
Identitätsdiebstahl eines nicht authentifizierten Nutzers
Wenn Sie öffentliche Vorgänge mit dem Admin SDK ausführen, sollten Sie den Vorgang nicht mit vollständigen Administratorberechtigungen ausführen (gemäß dem Prinzip der geringsten Berechtigung). Stattdessen sollten Sie den Vorgang entweder als Nutzer mit Identitätsübernahme (siehe nächster Abschnitt) oder als nicht authentifizierter Nutzer mit Identitätsübernahme ausführen. Nicht authentifizierte Nutzer können nur Vorgänge ausführen, die als PUBLIC gekennzeichnet sind.
// Query to get posts, with authentication level PUBLIC
const queryGetPostsImpersonation = `
query getPosts @auth(level: PUBLIC) {
posts {
description
}
}`;
// Attempt to access data as an unauthenticated user
const optionsUnauthenticated: GraphqlOptions<undefined> = {
impersonate: {
unauthenticated: true
}
};
// executeGraphql with impersonated unauthenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetPostsImpersonation, optionsUnauthenticated);
Übernahme der Nutzeridentität
Es gibt auch Anwendungsfälle, in denen Ihre Skripts Nutzerdaten im Namen eines bestimmten Nutzers mit eingeschränkten Anmeldedaten ändern sollen. Dieser Ansatz folgt dem Prinzip der geringsten Berechtigung.
Wenn Sie diese Schnittstelle verwenden möchten, müssen Sie Informationen aus einem benutzerdefinierten JWT-Authentifizierungstoken erfassen, das dem Authentication-Tokenformat entspricht. Weitere Informationen finden Sie im Leitfaden zu benutzerdefinierten Tokens.
// Get the current user's data
const queryGetUserImpersonation = `
query getUser @auth(level: USER) {
user(key: {uid_expr: "auth.uid"}) {
id,
name
}
}`;
// Impersonate a user with the specified auth claims
const optionsAuthenticated: GraphqlOptions<undefined> = {
impersonate: {
authClaims: {
sub: 'QVBJcy5ndXJ1'
}
}
};
// executeGraphql with impersonated authenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetUserImpersonation, optionsAuthenticated);
// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }
Administratoranmeldedaten verwenden
Wenn Sie einen Vorgang ausführen, für den Berechtigungen auf Administratorebene erforderlich sind, lassen Sie den Parameter „impersonate“ im Aufruf weg:
// User can be publicly accessible, or restricted to admins
const query = "query getProfile(id: AuthID) { user(id: $id) { id name } }";
interface UserData {
user: {
id: string;
name: string;
};
}
export interface UserVariables {
id: string;
}
const options:GraphqlOptions<UserVariables> = { variables: { id: "QVBJcy5ndXJ1" } };
// executeGraphql
const gqlResponse = await dataConnect.executeGraphql<UserData, UserVariables>(query, options);
// executeGraphqlRead (similar to previous sample but only for read operations)
const gqlResponse = await dataConnect.executeGraphqlRead<UserData, UserVariables>(query, options);
// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }
Ein auf diese Weise aufgerufener Vorgang hat vollständigen Zugriff auf die Datenbank. Wenn Sie Abfragen oder Mutationen haben, die nur für Verwaltungszwecke verwendet werden sollen, sollten Sie sie mit der Anweisung @auth(level: NO_ACCESS) definieren. Dadurch wird sichergestellt, dass nur Aufrufer auf Administratorebene diese Vorgänge ausführen können.
Bulk-Einfügevorgänge für Daten ausführen
Firebase empfiehlt, die Admin SDK für Bulk-Datenvorgänge in Produktionsdatenbanken zu verwenden.
Das SDK bietet die folgenden Methoden für die Arbeit mit Bulk-Daten. Aus den bereitgestellten Argumenten erstellt und führt jede Methode eine GraphQL-Mutation aus.
// Methods of the bulk operations API
// dc is a SQL Connect admin instance from getDataConnect
const resp = await dc.insert("movie" /*table name*/, data[0]);
const resp = await dc.insertMany("movie" /*table name*/, data);
const resp = await dc.upsert("movie" /*table name*/, data[0]);
const resp = await dc.upsertMany("movie" /*table name*/, data);
Verschachtelte relationale Vorgänge (1:n- und 1:1-Beziehungen)
Admin SDK unterstützt relationale Daten in Bulk-Vorgängen. Verwenden Sie wie bei benutzerdefinierten Mutationen ein Array von Objekten für 1:n-Beziehungen und ein einzelnes Objekt für 1:1-Beziehungen:
// Example of inserting a movie with nested reviews (one-to-many)
const moviesData = [
{
title: "Interstellar",
genre: "Sci-Fi",
reviews_on_movie: [
{
rating: 5,
reviewText: "Visually stunning and emotionally powerful.",
user: { id: "user-789" }
}
]
}
];
// Atomically insert movies and their reviews in a single database round-trip.
const response = await dc.insertMany("movie", moviesData);
// Example of inserting a user with a nested profile (one-to-one)
const usersData = [
{
name: "Alice",
profile_on_user: {
bio: "Avid moviegoer and critic."
}
}
];
// Atomically insert users and their profiles.
const userResponse = await dc.insertMany("user", usersData);
Hinweise zur Leistung bei Bulk-Vorgängen
Für jede Anfrage an das Backend ist ein Hin- und Rückflug zu Cloud SQL erforderlich. Je mehr Sie also im Batch verarbeiten, desto höher ist der Durchsatz.
Je größer jedoch die Batchgröße ist, desto länger ist die generierte SQL-Anweisung. Wenn die Längenbeschränkung für PostgreSQL-SQL-Anweisungen erreicht ist, tritt ein Fehler auf.
In der Praxis sollten Sie experimentieren, um die geeignete Batchgröße für Ihre Arbeitslast zu finden.
Nächste Schritte
- Datenbanken mit Daten über die Admin SDK füllen
- Sehen Sie sich die API für Admin SDK an.
- Verwenden Sie die Firebase-Befehlszeile und die Google Cloud-Konsole für andere Projektverwaltungsvorgänge, z. B. zum Verwalten von Schemas und Connectors und zum Verwalten von Diensten und Datenbanken.