Comienza a usar Firebase Data Connect

En esta guía de inicio rápido, aprenderás a realizar las siguientes tareas:

  • Agrega la conexión de datos de Firebase a tu proyecto de Firebase.
  • Configura un entorno de desarrollo que incluya una extensión de Visual Studio Code para que funcione con una instancia de producción.
  • A continuación, te mostraremos cómo hacer lo siguiente:
    • Crea un esquema a partir de un ejemplo de app de correo electrónico.
    • Define consultas y mutaciones para tu esquema.
    • Usa los SDK generados automáticamente para llamar a estas consultas y mutaciones desde tus clientes.
    • Implementa tu prototipo final en producción.

Requisitos previos

Para utilizar esta guía de inicio rápido, necesitarás lo siguiente.

Agrega Data Connect a tu proyecto y crea una fuente de datos

  1. Si aún no lo has hecho, crea un proyecto de Firebase.
    1. En Firebase console, haz clic en Agregar proyecto y sigue las instrucciones en pantalla.

  2. Actualiza tu proyecto al plan Blaze. Esto te permite crear una instancia de Cloud SQL para PostgreSQL.

  3. Ve a la sección Conexión de datos de Firebase console y sigue el flujo de trabajo de configuración del producto.

  4. Selecciona una ubicación para tu base de datos de Cloud SQL para PostgreSQL.

  5. Toma nota de los nombres y los IDs del proyecto, el servicio y la base de datos para confirmarlo más adelante.

  6. Sigue el proceso de configuración restante y, luego, haz clic en Listo.

Cómo elegir y configurar un entorno de desarrollo

Comenzarás con Data Connect mediante el prototipado de una app en Visual Studio Code.

De manera opcional, puedes instalar una base de datos local de PostgreSQL para el desarrollo local con el emulador de Data Connect. Esta configuración se describe al final de esta guía de inicio rápido.

Data Connect admite dos experiencias de desarrollo para el prototipado:

  • Si eres desarrollador web o de Kotlin Android, puedes crear prototipos de esquemas y operaciones de forma local mientras te conectas a tu instancia de Cloud SQL para PostgreSQL o, de forma opcional, ejecutar PostgreSQL de manera local.

  • Si eres desarrollador web, puedes usar IDX para crear prototipos en un lugar de trabajo de IDX con una plantilla de IDX preconfigurada con PostgreSQL, una extensión de VS Code con el emulador de Data Connect y el código de inicio rápido configurado para ti.

Desarrollo de VS Code

Si te gusta desarrollar de manera local en lugar de usar IDX, configura la extensión de Firebase VS Code que te ayudará a iterar tu desarrollo rápidamente con la generación de SDK para la Web, Kotlin para Android y, próximamente, iOS.

  1. Crea un directorio nuevo para tu proyecto local.
  2. Abre VS Code en el directorio nuevo.
  3. Descarga la extensión, incluida un paquete de VSIX, desde Firebase Storage.
  4. En VS Code, en el menú View, selecciona Extensions.
  5. En la barra de título del panel Extensiones, haz clic en el ícono de menú more_horiz y, luego, sigue las instrucciones en Instalar desde VSIX....

Desarrollo de IDX

IDX es un entorno optimizado para el desarrollo de apps web. Si eres desarrollador de Kotlin para Android, sigue los pasos que se indican en la pestaña Desarrollo de VS Code.

Para configurar una plantilla de IDX de Data Connect, sigue estos pasos:

  1. Accede a la plantilla en el sitio de Project IDX.
  2. Sigue el flujo de configuración.

Configura tu proyecto local

Instala la CLI. Para ello, sigue las instrucciones normales.

Luego, habilita el experimento de conexión de datos de Firebase.

firebase experiments:enable dataconnect

Para configurar tu proyecto local, inicializaremos el directorio del proyecto y actualizaremos algunos archivos de configuración necesarios para la generación de código.

Configura el directorio de tu proyecto

Inicializa el directorio de tu proyecto.

Configuración de extensiones de Firebase

En el panel izquierdo de VS Code, haz clic en el ícono de Firebase para abrir la IU de la extensión de Firebase VS Code.

En la IU de la extensión de Firebase, haz lo siguiente:

  1. Asegúrate de que accediste a tu cuenta.
  2. En Firebase console, confirma que se haya completado el flujo de configuración de Data Connect, incluido el aprovisionamiento de la base de datos.
  3. Haz clic en el botón Run firebase init.
  4. Revisa la pestaña Terminal en el panel inferior de VS Code para ver los mensajes.
  5. Selecciona Conexión de datos como una función para usar en este directorio.
  6. Cuando se te solicite, proporciona los IDs del proyecto, el servicio y la base de datos del proyecto de Data Connect que creaste anteriormente en la consola.

Configuración de la terminal

  1. Si es necesario, accede con firebase login.
  2. En Firebase console, confirma que se haya completado el flujo de configuración de Data Connect, incluido el aprovisionamiento de la base de datos.
  3. Ejecuta firebase init para inicializar el directorio como un proyecto de Firebase, según las instrucciones en pantalla.
  4. Selecciona Conexión de datos como una función para usar en este directorio.
  5. Cuando se te solicite, proporciona los IDs del proyecto, el servicio y la base de datos del proyecto de Data Connect que creaste anteriormente en la consola.

Cualquiera de los flujos creará archivos firebase.json y .firebaserc, y subdirectorios dataconnect, incluidos los archivos dataconnect.yaml y connector.yaml importantes en tu directorio de trabajo local.

Configura dónde se genera el código del SDK

Data Connect genera automáticamente el código del SDK mientras editas el esquema.

Si deseas especificar dónde se generan los SDK, actualiza el archivo para tu conector inicial en dataconnect/connector/connector.yaml.

connectorId: "my-connector"
authMode: "PUBLIC"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@email-manager/emails"
    packageJsonDir: "../../"
  kotlinSdk:
    outputDir: "../kotlin-email-generated"
    package: com.myemailapplication

Familiarízate con el kit de herramientas de Data Connect

Data Connect Toolkit es un componente de la extensión de Firebase VS Code que ayuda con el desarrollo de esquemas y la administración de consultas y mutaciones directamente desde Visual Studio Code.

Para conocer las funciones del kit de herramientas, haz lo siguiente:

  1. Si aún no lo has hecho, abre el directorio de tu proyecto de Firebase en VS Code.
  2. En el panel izquierdo de VS Code, haz clic en el ícono de Firebase para abrir la IU de la extensión de Firebase VS Code.

Durante tu trabajo de desarrollo, ten en cuenta que el kit de herramientas te permite interactuar con tu entorno local y con tus recursos de producción. En esta guía de inicio rápido, interactuarás con tu entorno de producción.

Extensión de VS Code para Data Connect en IDX

La IU de la extensión te proporciona varias funciones útiles:

En la barra lateral principal de VS Code, haz lo siguiente:

  • Un panel Config, que te permite acceder a Google y seleccionar un proyecto de Firebase
  • Un panel de Firebase Data Connect, que te permite controlar el emulador integrado y también implementar recursos en la producción.
  • Un panel del Explorador de FDC, que enumera consultas y mutaciones implícitas generadas automáticamente según tu esquema
En el panel inferior de VS Code, haz lo siguiente:

  • Una pestaña Data Connect Execution con herramientas que te permiten pasar datos en solicitudes, imitar la autenticación y ver resultados.

Antes de comenzar a desarrollar una app, observa algunas funciones de la extensión.

Prueba la función CodeLens personalizada Cuando trabajas con recursos en tus archivos schema.gql, queries.gql y mutations.gql, una vez que escribes bloques de código sintácticamente completos, un CodeLens personalizado muestra acciones que puedes realizar en tus tablas y operaciones declaradas.
  • En el caso de las tablas, CodeLens te ayuda a generar mutaciones para agregar datos a la base de datos del backend.
  • Para consultas y mutaciones, CodeLens te permite ejecutar las operaciones de forma local o en recursos de producción.
Configura el nivel de autenticación para las solicitudes En el panel inferior, el panel Data Connect Execution proporciona una pestaña Configuración en la que puedes seleccionar niveles de autenticación simulados para las operaciones.
Propaga variables en consultas y mutaciones En la misma pestaña Configuración, puedes propagar las cargas útiles de operación.
Cómo inspeccionar el historial, las respuestas y los errores Además, en la pestaña Configuración, puedes consultar las pestañas Historial y Resultados para obtener información de depuración.

Crea un esquema y una consulta de Data Connect

Se completó la configuración. Ahora podemos empezar a desarrollar con Data Connect.

Comienza a usar GraphQL para modelar usuarios y correos electrónicos. Actualizarás las fuentes en:

  • /dataconnect/schema/schema.gql
  • /dataconnect/connector/queries.gql

Comenzar a desarrollar un esquema

En el directorio de tu proyecto de Firebase, toma nota de la carpeta dataconnect. Aquí es donde defines tu modelo de datos para una base de datos de Cloud SQL con GraphQL.

En el archivo /dataconnect/schema/schema.gql, comienza a definir un esquema que incluya usuarios y correos electrónicos.

Usuario

En Conexión de datos, los campos de GraphQL se asignan a columnas. Los usuarios tienen un uid, un name y un correo electrónico address. Data Connect reconoce varios tipos de datos primitivos: String y Date.

Copia el siguiente fragmento o quita el comentario de las líneas correspondientes del archivo.

# File `/dataconnect/schema/schema.gql`

type User @table(key: "uid") {
   uid: String!
   name: String!
   address: String!
}

Según la configuración predeterminada, Firebase Data Connect agregará una clave de UUID id si no se proporciona ninguna. Sin embargo, en este caso, quieres que mi uid sea la clave primaria, lo que puedes hacer mediante la directiva @table(key: "uid").

Correo electrónico

Ahora que tienes usuarios, puedes modelar correos electrónicos. Aquí puedes agregar los campos (o columnas) típicos de los datos de correo electrónico. Esta vez, omitimos la adición de una clave primaria porque puedes confiar en Data Connect para administrarla.

# File `/dataconnect/schema/schema.gql`

type Email @table {
   subject: String!
   date: Date!
   text: String!
   from: User!
}

Ten en cuenta que el campo from está asignado a un tipo de User. Data Connect comprende que esta es una relación entre Email y User, y administrará esta relación por ti.

Implementa tu esquema en producción

Debido a que usas la extensión de Firebase VS Code para trabajar con tu base de datos de producción, debes implementar el esquema antes de continuar.

  1. Puedes usar la extensión de Firebase VS Code para realizar la implementación.
    • En la IU de la extensión, en el panel de Conexión de datos de Firebase, haz clic en Implementar.

  2. También puedes usar Firebase CLI.

    firebase deploy

  3. En el flujo de extensión o de la CLI, es posible que debas revisar los cambios de esquema y aprobar las modificaciones potencialmente destructivas. Se te pedirá lo siguiente:

    • Revisa los cambios del esquema con firebase dataconnect:sql:diff
    • Cuando estés conforme con los cambios, aplícalos con el flujo iniciado por firebase dataconnect:sql:migrate.

Observa las extensiones de esquema generadas

A medida que editas el esquema de correo electrónico, Data Connect genera de forma automática extensiones de esquema, consultas, mutaciones, filtros y relaciones de tablas. Puedes ver este código generado de dos maneras.

  • Puedes ver una lista de las consultas y mutaciones implícitas generadas en la IU de la extensión de Firebase, en el panel Explorador de FDC.
  • Puedes ver todo el código generado de forma local en las fuentes del directorio .dataconnect/schema.

Ejecuta una mutación para agregar datos a tu tabla

Puedes ver que los botones de CodeLens aparecen sobre los tipos de GraphQL en /dataconnect/schema/schema.gql.

Consultas y mutaciones de la hora de desarrollo

Las operaciones asociadas con estos botones de CodeLens son acciones rápidas y útiles, en este caso, agregar datos a la tabla. Data Connect usa mutaciones de GraphQL para describir cómo y quién puede operar en la base de datos. Con este botón, se crea una operación de tiempo de desarrollo para la propagación rápida de datos.

Una vez que hayas implementado tu esquema en producción, puedes usar los botones Run (Production) de CodeLens para realizar estas acciones en tu backend.

Escribe una consulta para enumerar correos electrónicos

Ahora, la parte divertida son las consultas. Como desarrollador, estás acostumbrado a escribir consultas en SQL en lugar de consultas en GraphQL, por lo que esto puede parecer un poco diferente al principio. Sin embargo, GraphQL es mucho más conciso y seguro de tipos que SQL sin procesar. Nuestra extensión de VS Code facilita la experiencia de desarrollo.

Comienza a editar el archivo /dataconnect/connector/queries.gql. Si quieres recibir todos los correos electrónicos, usa una consulta como esta.

# File `/dataconnect/connector/queries.gql`

query listEmails @auth(level: PUBLIC) {
  emails {
    id, subject, text, date
    from {
      name
    }
  }
}

Una función muy interesante es la capacidad de tratar las relaciones de la base de datos como un gráfico. Dado que un correo electrónico tiene un campo from que hace referencia a un usuario, puedes anidar en el campo y obtener información sobre el usuario.

directiva @auth

En este ejemplo, la directiva @auth no se está usando en su máximo potencial, pero el concepto es realmente poderoso. Así es como se decide la política de autorización para las operaciones en la base de datos.

Esta consulta es bastante sencilla: las funciones realmente interesantes de Data Connect comienzan a destacarse cuando realizas uniones más complejas con relaciones de varios a varios. Obtendrás más información sobre esto a medida que explores las herramientas y la documentación.

Prueba tu consulta

Ahora que creamos esta consulta, verifica si funciona antes de integrarla en el código del cliente. Una parte de la experiencia de los desarrolladores para Data Connect es la capacidad de iterar y probar rápidamente los resultados de la consulta con el panel Data Connect Execution.

Puedes proporcionar los argumentos que esta consulta necesita y, luego, hacer clic en el botón CodeLens sobre el nombre de la consulta. Esto ejecuta la consulta y muestra los resultados, para que puedas ver que funciona como se esperaba.

Cómo generar código de SDK cliente y datos de consultas desde una app cliente

Para cerrar el ciclo de desarrollo, integra esta consulta en el código del cliente.

Puedes escribir un cliente para demostrar cómo llamar a la consulta y manejar las respuestas del servicio de conexión de datos.

  1. Localiza las fuentes generadas de forma automática en la ubicación que especificaste con anterioridad en tu archivo connector.yaml.

  2. Agrega Firebase a tu proyecto, registra tu app y, luego, instala el SDK de Firebase Core correspondiente:

  3. Si no usas IDX, puedes configurar un cliente que se pueda llamar desde la línea de comandos.

JavaScript

Crea un archivo fuente, clientTest.js, y copia el siguiente código.

const { initializeApp } = require("firebase/app");
const {
  connectDataConnectEmulator,
  getDataConnect,
} = require("firebase/data-connect");
const { listEmails, connectorConfig } = require("@email-manager/emails");

// TODO: Replace the following with your app's Firebase project configuration
const firebaseConfig = {
  //...
};

const app = initializeApp(firebaseConfig);
const dc = getDataConnect(app, connectorConfig);

// Remove the following line to connect directly to production
connectDataConnectEmulator(dc, "localhost", 9399);

listEmails().then(res => {
  console.log(res.data.emails);
  process.exit(0);
});

Y puedes ejecutar tu cliente.

    node clientTest.js
Kotlin en Android

Crea un archivo fuente, clientTest.kt, y copia el siguiente código.

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    lifecycleScope.launch {
      val connector = MyConnector.instance
      connector.dataConnect.useEmulator() // Remove to connect to production
      try {
        println(connector.listEmails.execute().data.emails)
      } catch (e: Throwable) {
        println("ERROR: $e")
      }
    }
  }
}

Luego, haz lo siguiente:

  1. Ejecutar la actividad
  2. Comprueba el resultado del logcat de Android.

Implementa tu prototipo completo en producción.

Trabajaste en una iteración de desarrollo. Ahora puedes implementar el esquema, los datos, las consultas y las mutaciones en el servidor con la IU de extensión de Firebase o Firebase CLI, tal como lo hiciste con tu esquema.

Una vez implementado, el servicio de conexión de datos estará listo para procesar las operaciones de los clientes. La instancia de Cloud SQL para PostgreSQL se actualizará con el esquema y los datos generados y implementados finales.

(Opcional) Instala PostgreSQL de forma local

Instalar PostgreSQL de manera local e integrarlo en el emulador te permite crear un prototipo en un entorno de desarrollo completamente local.

Puedes instalar una instancia nueva de PostgreSQL o usar una instancia existente.

Instala PostgreSQL

Instala la versión 15.x de PostgreSQL siguiendo las instrucciones para tu plataforma.

Toma nota de los resultados de nombre de host, puerto, nombre de usuario y contraseña, además de los parámetros relacionados, durante la secuencia de instalación.

Para conectarse a tu instancia de PostgreSQL, el emulador necesita lo siguiente:

  • Estos parámetros de configuración
  • El nombre de la base de datos de tu dataconnect.yaml y una base de datos con el nombre correspondiente inicializada en tu instancia local.

Actualiza tu .firebaserc con la string de conexión.

Usa los detalles de configuración de PostgreSQL local, incluidos tu nombre de usuario y contraseña de PostgreSQL local, para obtener una cadena de conexión para agregar a la siguiente clave en el archivo .firebaserc.

{
  "projects": {},
  ...,
  ...,
  "dataconnectEmulatorConfig": {
    "postgres": {
      "localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
    }}
}

Conéctate a tu instancia local de PostgreSQL

Una vez configurada esta configuración, haz lo siguiente para conectarte a tu base de datos local:

  1. En el panel izquierdo de VS Code, haz clic en el ícono de Firebase para abrir la IU de la extensión de Firebase VS Code.
  2. Haz clic en el botón Conectar a PostgreSQL local.

Próximos pasos