Usar o SDK Admin com o Data Connect

O Firebase Admin SDK é um conjunto de bibliotecas de servidor que permite interagir com o Firebase usando 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 falsificadas.

O Admin SDK fornece 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 você precisa instalar e configurar o Admin SDK para Node.js.

Inicializar o SDK Admin nos 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 Data Connect, considerando as seguintes considerações.

Entender a diretiva de operação do SDK e @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 administrativas e as mutações em arquivos de origem .gql para importação em scripts administrativos, o Firebase recomenda marcar as operações administrativas sem nenhum nível de acesso de autorização ou, talvez, ser mais explícito e defini-las como NO_ACCESS. De qualquer forma, isso impede que essas operações sejam executadas de clientes ou em outros contextos sem privilégios.

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, já que ignora a autenticação e a autorização para fluxos locais.

Os SDKs Admin do Firebase se conectam automaticamente ao emulador do 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 o código implementa consultas e mutações e as transmite ao método executeGraphql de leitura/gravação ou ao método executeGraphqlRead somente leitura.
  • 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 para o Admin SDK é gerenciar dados do usuário.

Usar credenciais administrativas

A abordagem mais simples é 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" } } }

Falsificar credenciais do usuário

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

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

Você pode trabalhar com dados acessíveis publicamente usando o SDK, falsificando 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 o uso do 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 constrói e executa uma mutação 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 para o back-end vai gerar uma ida e volta para o Cloud SQL. Portanto, quanto maior o lote, maior 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, você vai encontrar um erro.

Na prática, teste para encontrar o tamanho de lote adequado para sua carga de trabalho.

A seguir