Generierte Admin SDKs verwenden

Firebase Data Connect Admin SDKs können Sie Ihre Abfragen und Mutationen aus vertrauenswürdigen Umgebungen wie Cloud Functions, benutzerdefinierten Back-Ends oder Ihrer eigenen Workstation aufrufen. Ähnlich wie beim Generieren von SDKs für Ihre Client-Apps können Sie parallel ein benutzerdefiniertes Admin SDK generieren, während Sie die Schemas, Abfragen und Mutationen entwerfen, die Sie für Ihren Data Connect Dienst bereitstellen. Anschließend binden Sie Methoden aus diesem SDK in Ihre Back-End-Logik oder Verwaltungsskripts ein.

Wie bereits erwähnt, werden Data Connect Abfragen und Mutationen nicht von Clients zum Zeitpunkt der Anfrage gesendet. Stattdessen werden Data Connect Vorgänge nach der Bereitstellung wie Cloud Functions auf dem Server gespeichert. Wenn Sie also Änderungen an Ihren Abfragen und Mutationen bereitstellen, müssen Sie auch Admin SDKs neu generieren und alle Dienste neu bereitstellen, die darauf angewiesen sind.

Hinweis

Informationen zum Entwerfen von Data Connect Schemas, Abfragen und Mutationen. In einem typischen Workflow entwickeln Sie diese parallel zu Ihrem Anwendungscode, einschließlich aller Dienste, die Admin SDKs verwenden.
Installieren Sie die Firebase CLI.

Hinweis: Sie können Firebase CLI-Befehle auch in Cloud Shell ausführen. Cloud Shell ist eine browserbasierte, vorauthentifizierte Befehlszeilenumgebung, auf die Sie über die Firebase Konsole zugreifen können. Die Firebase CLI ist vorinstalliert. Das ist eine praktische Option für den schnellen Einstieg, sofern Sie Ihre Projektdateien der Cloud Shell Umgebung hinzufügen.
Fügen Sie das Admin SDK für Node.js als Abhängigkeit hinzu, wenn Sie die generierten Admin SDKs aufrufen möchten.

Admin SDKs generieren

Nachdem Sie Ihre Data Connect Schemas, Abfragen und Mutationen erstellt haben, können Sie ein entsprechendes Admin SDK generieren:

Öffnen oder erstellen Sie eine connector.yaml-Datei und fügen Sie eine adminNodeSdk-Definition hinzu:
```
connectorId: default
generate:
  adminNodeSdk:
    outputDir: ../../dataconnect-generated/admin-generated
    package: "@dataconnect/admin-generated"
    packageJsonDir: ../..
```
Die Datei connector.yaml befindet sich normalerweise im selben Verzeichnis wie die GraphQL-Dateien (.gql), die Ihre Abfrage- und Mutationsdefinitionen enthalten. Wenn Sie bereits Client SDKs generiert haben, wurde diese Datei bereits erstellt.
Generieren Sie das SDK.

Wenn Sie die Data Connect VS Code-Erweiterung installiert haben, werden generierte SDKs immer auf dem neuesten Stand gehalten.

Verwenden Sie andernfalls die Firebase CLI:
```
firebase dataconnect:sdk:generate
```
Alternativ können Sie SDKs automatisch neu generieren, wenn Sie Ihre gql-Dateien aktualisieren:
```
firebase dataconnect:sdk:generate --watch
```

Vorgänge über ein Admin SDK ausführen

Das generierte Admin SDK enthält Schnittstellen und Funktionen, die Ihren gql-Definitionen entsprechen. Damit können Sie Vorgänge in Ihrer Datenbank ausführen. Angenommen, Sie haben ein SDK für eine Datenbank mit Songs zusammen mit einer 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ät eines nicht authentifizierten Nutzers annehmen

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 (Prinzip der geringsten Berechtigung). Stattdessen sollten Sie den Vorgang entweder als imitierter Nutzer (siehe nächster Abschnitt) oder als imitierter nicht authentifizierter Nutzer 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.

Identität eines Nutzers annehmen

Sie können auch Vorgänge im Namen bestimmter Nutzer ausführen, indem Sie einen Teil oder das gesamte Firebase Authentication Token in der impersonate Option übergeben. Sie müssen mindestens die Nutzer-ID des Nutzers im Anspruch „sub“ angeben. (Das ist derselbe Wert wie der auth.uid Serverwert , auf den Sie in Data Connect GraphQL-Vorgängen verweisen können.)

Wenn Sie die Identität eines Nutzers annehmen, 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 über einen öffentlich zugänglichen Endpunkt aufrufen, ist es wichtig, dass der Endpunkt eine Authentifizierung erfordert und dass Sie die Integrität des Authentifizierungstokens prüfen, bevor Sie es verwenden, um die Identität eines Nutzers anzunehmen.

Bei der Verwendung von aufrufbaren Cloud Functions 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 } }
    );

    // ...
});

Verwenden Sie andernfalls die Admin SDK's verifyIdToken Methode, um das Authentifizierungstoken zu validieren und zu decodieren. Angenommen, Ihr Endpunkt ist als eine einfache HTTP-Funktion implementiert und Sie haben das Firebase Authentication Token wie üblich über den 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 Verwaltungsaufgaben 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 } }
);

Mit uneingeschränktem Zugriff ausführen

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 Direktive @auth(level: NO_ACCESS) definieren. So können nur Aufrufer auf Administratorebene diese Vorgänge ausführen.