Używanie pakietu Admin SDK z usługą Data Connect

Firebase Admin SDK to zestaw bibliotek serwera, który umożliwia interakcję z Firebase w środowiskach uprzywilejowanych w celu wykonywania działań takich jak zapytania i mutacje w usłudze Firebase Data Connect na potrzeby zarządzania danymi zbiorczymi oraz innych operacji z uprzywilejowanym dostępem i podszywaniem się pod tożsamość.

Admin SDK udostępnia interfejs API do wywoływania operacji w trybach odczytu/zapisu i tylko do odczytu. Operacje tylko do odczytu zapewniają spokój ducha, ponieważ umożliwiają wdrażanie funkcji administracyjnych, które nie mogą modyfikować danych w bazach danych.

Konfiguracja pakietu Admin SDK

Aby zacząć korzystać z Firebase Data Connect na serwerze, musisz najpierw zainstalować i skonfigurować Admin SDK dla Node.js.

Inicjowanie pakietu Admin SDK w skryptach

Aby zainicjować pakiet SDK, zaimportuj rozszerzenia Data Connect i zadeklaruj identyfikator usługi projektu oraz lokalizację.


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'
});

Tworzenie zapytań i mutacji do użycia z Admin SDK

Admin SDK jest przydatne do testowania operacji Data Connect, biorąc pod uwagę te kwestie:

Poznaj pakiet SDK i dyrektywę operacji @auth(level: NO_ACCESS)

Ponieważ Admin SDK działa z uprawnieniami, może wykonywać wszystkie Twoje zapytania i mutacje niezależnie od poziomów dostępu ustawionych za pomocą @auth dyrektyw, w tym na poziomie NO_ACCESS.

Jeśli oprócz operacji na klientach organizujesz zapytania administracyjne i mutacje w .gql plikach źródłowych do importowania do skryptów administracyjnych, Firebase zaleca oznaczanie operacji administracyjnych bez żadnego poziomu dostępu do autoryzacji lub bardziej wyraźne ustawianie ich jako NO_ACCESS. W obu przypadkach uniemożliwia to wykonywanie takich operacji przez klientów lub w innych kontekstach bez uprawnień.

Używanie pakietu SDK z emulatorem Data Connect

W środowiskach prototypowych i testowych może być przydatne wypełnianie danych i wykonywanie innych operacji na danych lokalnych. Flaga Admin SDK upraszcza przepływy pracy, ponieważ ignoruje uwierzytelnianie i autoryzację w przypadku przepływów lokalnych.

Pakiety Firebase Admin SDK automatycznie łączą się z Data Connectemulatorem, gdy ustawiona jest zmienna środowiskowa DATA_CONNECT_EMULATOR_HOST:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

Aby dowiedzieć się więcej, zobacz:

Implementowanie typowych przypadków użycia

Admin SDK jest zapewniana w przypadku operacji uprzywilejowanych na danych o znaczeniu krytycznym.

Pakiet Admin SDK udostępnia 2 interfejsy:

  • Ogólny interfejs dla większości operacji odczytu i zapisu lub tylko do odczytu, w którym kod implementuje zapytania i mutacje oraz przekazuje je do metody odczytu i zapisu executeGraphql lub metody tylko do odczytu executeGraphqlRead.
  • Specjalistyczny interfejs do operacji na danych zbiorczych, który zamiast ogólnych metod executeGraphql udostępnia dedykowane metody operacji modyfikacji: insert, insertMany, upsert i upsertMany.

Zarządzanie danymi użytkowników za pomocą metod executeGraphql

Typowym zastosowaniem Admin SDK jest zarządzanie danymi użytkowników.

Używanie danych logowania administratora

Najprostszym sposobem jest uzyskanie dostępu do danych użytkownika za pomocą danych logowania administratora.

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

Odgrywanie roli innego użytkownika

Istnieją też przypadki, w których chcesz, aby skrypty modyfikowały dane użytkownika na podstawie ograniczonych danych logowania w imieniu konkretnego użytkownika. To podejście jest zgodne z zasadą jak najmniejszych uprawnień.

Aby korzystać z tego interfejsu, zbierz informacje z dostosowanego tokena uwierzytelniania JWT, który jest zgodny z Authentication formatem tokena. Zapoznaj się też z przewodnikiem po tokenach niestandardowych.

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

Zarządzanie danymi publicznymi za pomocą metod executeGraphql

Za pomocą pakietu SDK możesz pracować z danymi dostępnymi publicznie, podszywając się pod nieuwierzytelnionego użytkownika.

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

Wykonywanie operacji na danych zbiorczych

W przypadku operacji na danych zbiorczych w bazach danych produkcyjnych Firebase zaleca używanie Admin SDK.

Pakiet SDK udostępnia te metody pracy z danymi zbiorczymi. Na podstawie podanych argumentów każda metoda tworzy i wykonuje mutację GraphQL.


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

Uwagi dotyczące wydajności operacji zbiorczych

Każde żądanie do backendu powoduje jedną podróż w obie strony do Cloud SQL, więc im więcej żądań zgrupujesz, tym większa będzie przepustowość.

Im większy rozmiar partii, tym dłuższe jest wygenerowane polecenie SQL. Gdy zostanie osiągnięty limit długości polecenia SQL w PostgreSQL, pojawi się błąd.

W praktyce eksperymentuj, aby znaleźć odpowiedni rozmiar partii dla swojego obciążenia.

Co dalej?