Usar SDKs da Web gerados

Observação: o Firebase Data Connect está no Acesso antecipado. O Data Connect está sujeito aos "Termos das ofertas pré-GA" na seção Termos específicos de serviço dos Termos de Serviço do Google Cloud Platform. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Os SDKs do cliente do Firebase Data Connect permitem chamar consultas e mutações do lado do servidor diretamente de um app do Firebase. Você gera um SDK do cliente personalizado em paralelo ao projetar os esquemas, consultas e mutações que serão implantados no serviço Data Connect. Em seguida, integre os métodos desse SDK à lógica do cliente.

Como mencionamos em outro lugar, é importante observar que as consultas e mutações Data Connect não são enviadas pelo código do cliente e executadas no servidor. Em vez disso, quando implantadas, as operações Data Connect são armazenadas no servidor, como o Cloud Functions. Isso significa que você precisa implantar as mudanças correspondentes do lado do cliente para evitar problemas com usuários existentes (por exemplo, em versões mais antigas do app).

Por isso, o Data Connect oferece um ambiente de desenvolvimento e ferramentas que permitem criar protótipos de esquemas, consultas e mutações implantados no servidor. Ele também gera SDKs do lado do cliente automaticamente enquanto você cria o protótipo.

Depois de iterar as atualizações nos apps de serviço e cliente, as atualizações do lado do servidor e do cliente estão prontas para implantação.

Gerar o SDK da Web

Como na maioria dos projetos do Firebase, o trabalho no código do cliente Firebase Data Connect acontece em um diretório de projeto local. A extensão do Data Connect para VS Code e a CLI Firebase são ferramentas locais importantes para gerar e gerenciar o código do cliente.

As opções de geração do SDK são vinculadas a várias entradas no arquivo dataconnect.yaml gerado quando você inicializou o projeto.

Inicializar a geração do SDK

No connector.yaml, adicione outputDir, package e (para o SDK da Web) packageJsonDir.

generate:
  javascriptSdk:
    outputDir: "../movies-generated"
    package: "@movie-app/movies"
    packageJsonDir: "../../"

outputDir especifica onde o SDK gerado vai ser gerado.

package especifica o nome do pacote.

packageJsonDir especifica onde instalar o pacote.

Observação: para geração, adicionamos "firebase": "^10.14.0" como um peerDependency. Dependendo do gerenciador de dependências (por exemplo, pnpm), essas dependências podem não ser instaladas automaticamente.

Nesse caso, instale firebase@latest para garantir que essa dependência de peer seja atendida.

Configurar caminhos relativos a node_modules

No SDK da Web, como Data Connect usa npm link para instalar o SDK, o SDK gerado precisa ser gerado em um diretório no mesmo nível do caminho node_modules ou em um diretório filho que possa acessar node_modules.

Em outras palavras, o SDK gerado precisa ter acesso ao módulo de nó firebase para funcionar corretamente.

Por exemplo, se você tiver node_modules em my-app/, o diretório de saída precisa ser my-app/js-email-generated para que js-email-generated possa importar da pasta mãe node_modules.

my-app/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  js-email-generated/

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@myapp/my-connector"

Ou, se você tiver um monorepo em que seus módulos são hospedados na raiz, é possível colocar o diretório de saída em qualquer pasta no monorepo.

my-monorepo/
  dataconnect/
    connector/
        connector.yaml
  node_modules/
    firebase/
  my-app/
    js-email-generated/
  package.json

// connector.yaml
connectorId: "my-connector"
generate:
  javascriptSdk:
    outputDir: "../../my-app/js-email-generated" # You can also output to ../../js-email-generated

Observação: é possível fornecer um caminho absoluto para diretórios se o projeto estiver configurado em uma estrutura de diretórios separada.

Atualizar SDKs durante a prototipagem

Se você estiver criando protótipos de forma interativa com a extensão do Data Connect para o VS Code e o emulador Data Connect, os arquivos de origem do SDK serão gerados e atualizados automaticamente enquanto você modifica arquivos .gql que definem esquemas, consultas e mutações. Esse pode ser um recurso útil em fluxos de trabalho de (re)carregamento em tempo real.

Em outros cenários, se você estiver usando o emulador Data Connect da CLI Firebase, poderá definir um monitoramento nas atualizações .gql e também ter as origens do SDK atualizadas automaticamente.

Como alternativa, use a CLI para regenerar SDKs sempre que os arquivos .gql forem alterados:

firebase dataconnect:sdk:generate --watch

Gerar SDKs para integração e lançamentos de produção

Em alguns casos, como ao preparar fontes de projeto para envio para testes de CI, é possível chamar a CLI Firebase para uma atualização em lote.

Nesses casos, use firebase dataconnect:sdk:generate.

Configurar o código do cliente

Inicializar o app Data Connect

Primeiro, inicialize o app usando a sequência padrão do Firebase.

initializeApp({...});

Inicializar o SDK da Web Data Connect

Inicialize sua instância do Data Connect usando as informações que você usou para configurar o Data Connect (todas disponíveis na guia "Data Connect" do console do Firebase).

O objeto ConnectorConfig

O SDK requer um objeto de configuração do conector.

Esse objeto é gerado automaticamente de serviceId e location em dataconnect.yaml e connectorId em connector.yaml.

Importar bibliotecas

Há dois conjuntos de importações necessários para inicializar o código do cliente: importações Data Connect gerais e importações específicas e geradas do SDK.

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@myorg/myconnector';

Desenvolver protótipos e testar clientes da Web

Instrumentar clientes para usar um emulador local

É possível usar o emulador Data Connect, seja na extensão do Data Connect para o VS Code ou na CLI.

A instrumentação do app para se conectar ao emulador é a mesma para os dois cenários.

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@myorg/myconnector'; // Replace with your package name
const dataConnect = getDataConnect(connectorConfig);

connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

Para alternar para recursos de produção, comente as linhas para se conectar ao emulador.

Como acessar uma instância

A chamada de getDataConnect só é necessária se você quiser se conectar ao emulador Data Connect. Caso contrário, o SDK gerado vai criar automaticamente uma instância do objeto DataConnect para você.

Como usar consultas no lado do cliente

O código gerado já vem com referências de consulta predefinidas. Basta importar e chamar a execução neles.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@movie-app/movies';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

Chamar métodos de consulta do SDK

Confira um exemplo com essas funções de atalho de ação:

import { listMovies } from '@movie-app/movies';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out // to the server.
listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}

Como receber notificações sobre mudanças

Você pode se inscrever para receber notificações de mudanças, que são atualizadas sempre que você executa uma consulta.

const listRef = listAllMoviesRef();

// subscribe will immediately invoke the query if no execute was called on it previously.
subscribe(listRef, ({ data }) => {
 updateUIWithMovies(data.movies);
});

await createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi", rating: 5 });\
await listMovies(); // will update the subscription above`

Como usar mutações no lado do cliente

As mutações podem ser acessadas da mesma forma que as consultas.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@movie-app/movies';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

Tipos de dados no SDK da Web

O servidor Data Connect representa tipos de dados comuns do GraphQL. Elas são representadas no SDK da seguinte maneira.

Tipo de conexão de dados	TypeScript
Carimbo de data/hora	string
Data	string
UUID	string
Int64	string
Duplo	Número
Ponto flutuante	Número

Considerações sobre frameworks

Angular

Ao gerar o código, o Angular CLI não vai detectar novas mudanças devido ao código de otimização de dependência. Para corrigir isso, você precisa modificar o angular.json.

  "projects": {
      "myproject": {
         "architect": {
                 "serve:": {
                            "prebundle": {
                                         "exclude": ["@movie-app/movies"]
                              }
                   }
            }
     }
  }