Admin SDK mit Data Connect verwenden

Die Firebase Admin SDK ist eine Reihe von Serverbibliotheken, mit denen Sie in privilegierten Umgebungen mit Firebase interagieren können, um Aktionen wie das Ausführen von Abfragen und Mutationen für einen Firebase Data Connect-Dienst zur Massendatenverwaltung und andere Vorgänge mit erhöhten Berechtigungen und imitierten Anmeldedaten auszuführen.

Die Admin SDK bietet eine API zum Aufrufen von Vorgängen im Lese-/Schreibmodus und im schreibgeschützten Modus. Mit den schreibgeschützten Vorgängen können Sie administrative Funktionen implementieren, die keine Daten in Ihren Datenbanken ändern können.

Admin SDK einrichten

Wenn Sie Firebase Data Connect auf Ihrem Server verwenden möchten, müssen Sie zuerst Admin SDK für Node.js installieren und einrichten.

Admin SDK in Ihren Skripts initialisieren

Um das SDK zu initialisieren, importieren Sie die Data 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 Admin SDK entwerfen

Der Admin SDK ist nützlich, um Data Connect-Vorgänge zu testen. Dabei sind die folgenden Aspekte zu berücksichtigen.

SDK und @auth(level: NO_ACCESS)-Vorgangsanweisung

Da der Admin SDK mit Berechtigungen arbeitet, kann er alle Ihre Abfragen und Mutationen unabhängig von den mit @auth-Anweisungen festgelegten Zugriffsebenen ausführen, einschließlich der Ebene NO_ACCESS.

Wenn Sie neben Ihren Clientvorgängen Ihre administrativen Abfragen und Mutationen in .gql-Quelldateien für den Import in administrative Skripts organisieren, empfiehlt Firebase, die administrativen Vorgänge ohne Autorisierungszugriffsebene zu kennzeichnen oder sie expliziter als NO_ACCESS festzulegen. So oder so wird verhindert, dass solche Vorgänge von Clients oder in anderen nicht privilegierten Kontexten ausgeführt werden.

SDK mit dem Data 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 Arbeitsabläufe vereinfachen, da die Authentifizierung und Autorisierung für lokale Abläufe ignoriert werden.

Die Firebase Admin SDKs stellen automatisch eine Verbindung zum Data 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:

Gängige Anwendungsfälle implementieren

Die Admin SDK wird für privilegierte Vorgänge für Ihre wichtigen Daten bereitgestellt.

Das Admin SDK bietet zwei Schnittstellen:

  • Eine allgemeine Schnittstelle für die meisten Lese-/Schreib- oder schreibgeschützten Vorgänge, in der Ihr Code Abfragen und Mutationen implementiert und an die Lese-/Schreibmethode executeGraphql oder die schreibgeschützte Methode executeGraphqlRead übergibt.
  • Eine spezielle Schnittstelle für Bulk-Datenvorgänge, die anstelle generischer executeGraphql-Methoden spezielle Methoden für Mutationsvorgänge bereitstellt: insert, insertMany, upsert und upsertMany.

Nutzerdaten mit executeGraphql-Methoden verwalten

Ein typischer Anwendungsfall für die Admin SDK ist die Verwaltung von Nutzerdaten.

Administratoranmeldedaten verwenden

Am einfachsten ist es, mit Administratoranmeldedaten auf Nutzerdaten zuzugreifen.

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

Nutzeranmeldedaten imitieren

Es gibt auch Anwendungsfälle, in denen Sie möchten, dass Ihre Skripts Nutzerdaten im Namen eines bestimmten Nutzers auf Grundlage eingeschränkter Anmeldedaten ändern. Dieser Ansatz entspricht dem Prinzip der geringsten Berechtigung.

Um diese Schnittstelle zu verwenden, müssen Sie Informationen aus einem benutzerdefinierten JWT-Authentifizierungstoken abrufen, das dem Tokenformat Authentication 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" } } }

Öffentliche Daten mit executeGraphql-Methoden verwalten

Mit dem SDK können Sie mit öffentlich zugänglichen Daten arbeiten und die Identität eines nicht authentifizierten Nutzers annehmen.

// 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);

Bulk-Datenvorgänge ausführen

Firebase empfiehlt die Verwendung von Admin SDK für Massendatenvorgänge in Produktionsdatenbanken.

Das SDK bietet die folgenden Methoden für die Arbeit mit Bulk-Daten. Aus den bereitgestellten Argumenten wird mit jeder Methode eine GraphQL-Mutation erstellt und ausgeführt.


// Methods of the bulk operations API
// dc is a Data 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);

Hinweise zur Leistung bei Bulk-Vorgängen

Für jede Anfrage an das Backend ist ein Roundtrip zu Cloud SQL erforderlich. Je mehr Sie also in Batches zusammenfassen, desto höher ist der Durchsatz.

Je größer die Batchgröße ist, desto länger ist jedoch die generierte SQL-Anweisung. Wenn das Längenlimit für PostgreSQL-SQL-Anweisungen erreicht ist, tritt ein Fehler auf.

In der Praxis sollten Sie experimentieren, um die passende Batchgröße für Ihre Arbeitslast zu ermitteln.

Nächste Schritte