Usar o SDK Admin com o Data Connect

O Firebase Admin SDK é um conjunto de bibliotecas de servidor que permite interagir com o Firebase em ambientes privilegiados para executar ações como consultas e mutações em um serviço Firebase Data Connect para gerenciamento de dados em massa e outras operações com privilégios elevados e credenciais representadas.

A Admin SDK oferece uma API para chamar operações nos modos de leitura/gravação e somente leitura. Com as operações somente leitura, você tem a tranquilidade de implementar funções administrativas que não podem modificar dados nos seus bancos de dados.

Configuração do SDK Admin

Para começar a usar o Firebase Data Connect no seu servidor, primeiro instale e configure o Admin SDK para Node.js.

Inicializar o SDK Admin nos seus scripts

Para inicializar o SDK, importe as extensões Data Connect e declare o ID e o local do serviço do projeto.


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

Projetar consultas e mutações para usar com o Admin SDK

O Admin SDK é útil para testar operações de Data Connect, considerando as seguintes considerações.

Entender o SDK e a diretiva de operação @auth(level: NO_ACCESS)

Como o Admin SDK opera com privilégios, ele pode executar qualquer uma das suas consultas e mutações, independentemente dos níveis de acesso definidos usando diretivas @auth, incluindo o nível NO_ACCESS.

Se, além das operações do cliente, você organizar as consultas e mutações administrativas em arquivos de origem .gql para importação em scripts administrativos, o Firebase recomenda que você marque as operações administrativas sem nenhum nível de acesso de autorização ou seja mais explícito e as defina como NO_ACCESS. De qualquer forma, isso impede que essas operações sejam executadas em clientes ou em outros contextos não privilegiados.

Usar o SDK com o emulador Data Connect

Em ambientes de protótipo e teste, pode ser útil realizar a geração de dados e outras operações em dados locais. O Admin SDK simplifica seus fluxos de trabalho porque ignora a autenticação e a autorização para fluxos locais.

Os SDKs Admin do Firebase se conectam automaticamente ao emulador Data Connect quando a variável de ambiente DATA_CONNECT_EMULATOR_HOST está definida:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

Confira mais informações:

Implemente casos de uso comuns

O Admin SDK é fornecido para operações privilegiadas nos seus dados críticos.

O SDK Admin oferece duas interfaces:

  • Uma interface geral para a maioria das operações de leitura/gravação ou somente leitura, em que seu código implementa consultas e mutações e as transmite para o método de leitura/gravação executeGraphql ou o método somente leitura executeGraphqlRead.
  • Uma interface especializada para operações de dados em massa que, em vez de métodos genéricos executeGraphql, expõe métodos dedicados para operações de mutação: insert, insertMany, upsert e upsertMany.

Gerenciar dados do usuário com métodos executeGraphql

Um caso de uso típico do Admin SDK é o gerenciamento de dados do usuário.

Usar credenciais administrativas

A abordagem mais direta é acessar os dados do usuário usando credenciais administrativas.

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

Representar credenciais de usuário

Há também casos de uso em que você quer que seus scripts modifiquem os dados do usuário com base em credenciais limitadas, em nome de um usuário específico. Essa abordagem segue o princípio do menor privilégio.

Para usar essa interface, colete informações de um token de autenticação JWT personalizado que segue o formato de token Authentication. Consulte também o guia de tokens personalizados.

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

Gerenciar dados públicos com métodos executeGraphql

É possível trabalhar com dados acessíveis publicamente usando o SDK, representando um usuário não autenticado.

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

Realizar operações de dados em massa

O Firebase recomenda usar o Admin SDK para operações de dados em massa em bancos de dados de produção.

O SDK oferece os seguintes métodos para trabalhar com dados em massa. Com base nos argumentos fornecidos, cada método cria e executa uma mutação do 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);

Observações de desempenho para operações em massa

Cada solicitação ao back-end gera uma viagem de ida e volta ao Cloud SQL. Portanto, quanto mais você agrupar, maior será a capacidade.

No entanto, quanto maior o tamanho do lote, maior será a instrução SQL gerada. Quando o limite de comprimento da instrução SQL do PostgreSQL for atingido, um erro vai ocorrer.

Na prática, faça testes para encontrar o tamanho de lote adequado à sua carga de trabalho.

A seguir