Admin SDK mit Data Connect verwenden

Die Firebase Admin SDK ist eine Reihe von Serverbibliotheken, mit denen Sie aus privilegierten Umgebungen mit Firebase interagieren können, um Aktionen wie Abfragen und Mutationen für einen Firebase Data Connect-Dienst zur Bulk-Datenverwaltung und andere Vorgänge mit erhöhten Berechtigungen und Identitätsdiebstahl durchzuführen.

Die Admin SDK bietet eine API, mit der Vorgänge sowohl im Lese-/Schreib- als auch im schreibgeschützten Modus aufgerufen werden können. Bei schreibgeschützten Vorgängen können Sie Verwaltungsfunktionen implementieren, mit denen keine Daten in Ihren Datenbanken geändert werden können.

Admin SDK einrichten

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

Admin SDK in Ihren Scripts initialisieren

Um das SDK zu initialisieren, importieren Sie die Data Connect-Erweiterungen und deklarieren Sie die ID und den Speicherort Ihres Projektdiensts.


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 Admin SDK entwerfen

Die Admin SDK ist für das Testen von Data Connect-Vorgängen unter Berücksichtigung der folgenden Aspekte nützlich.

SDK und @auth(level: NO_ACCESS)-Vorgangsanweisung

Da Admin SDK mit Berechtigungen arbeitet, kann es alle Abfragen und Mutationen unabhängig von den Zugriffsebenen ausführen, die mit @auth-Direktiven festgelegt wurden, einschließlich der Ebene NO_ACCESS.

Wenn Sie neben Ihren Client-Vorgängen auch administrative Abfragen und Mutationen in .gql-Quelldateien für den Import in Verwaltungsscripts organisieren, empfiehlt Firebase, die Verwaltungsvorgänge ohne Autorisierungszugriffsebene zu kennzeichnen oder sie 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 Data Connect-Emulator verwenden

In Prototypen- und Testumgebungen kann es hilfreich sein, Daten zu erzeugen und andere Vorgänge auf lokalen Daten auszuführen. Mit Admin SDK können Sie Ihre Workflows vereinfachen, da 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

Der Admin SDK wird für privilegierte Vorgänge auf Ihre kritischen 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-Schreib-Methode executeGraphql oder die schreibgeschützte Methode executeGraphqlRead weitergibt.
  • Eine spezielle Schnittstelle für Bulk-Datenoperationen, die anstelle von generischen 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" } } }

Identität eines anderen Nutzers annehmen

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

Wenn du diese Schnittstelle verwenden möchtest, musst du 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" } } }

Öffentliche Daten mit executeGraphql-Methoden verwalten

Sie können mithilfe des SDKs mit öffentlich zugänglichen Daten arbeiten und sich als nicht authentifizierter Nutzer ausgeben.

// 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 Admin SDK für Bulk-Datenvorgänge in Produktionsdatenbanken zu verwenden.

Das SDK bietet die folgenden Methoden für die Arbeit mit Bulk-Daten. Jede Methode konstruiert und führt anhand der angegebenen Argumente eine GraphQL-Mutation aus.


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

Leistungshinweise für Bulk-Vorgänge

Jede Anfrage an das Backend erfordert einen Hin- und Rücklauf zu Cloud SQL. Je mehr Batches Sie verwenden, desto höher ist der Durchsatz.

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

Experimentieren Sie in der Praxis, um die richtige Batchgröße für Ihre Arbeitslast zu ermitteln.

Nächste Schritte