Pierwsze kroki z Firebase Data Connect

Z tego krótkiego wprowadzenia dowiesz się, jak:

• Dodaj Firebase Data Connect do projektu Firebase.
• Skonfiguruj środowisko programistyczne z rozszerzeniem Visual Studio Code, aby pracować z instancją produkcyjną.
• Następnie pokażemy Ci, jak:
  • Utwórz schemat, korzystając z przykładowej aplikacji do poczty e-mail.
  • Określ zapytania i mutacje schematu.
  • Używaj automatycznie generowanych pakietów SDK do wywoływania tych zapytań i mutacji przez klientów.
  • Wdróż swój ostateczny prototyp w środowisku produkcyjnym.

Wymagania wstępne

Aby skorzystać z tego krótkiego wprowadzenia, musisz mieć:

• Linux, macOS lub Windows
• Visual Studio Code

Dodaj Data Connect do projektu i utwórz źródło danych

1. Utwórz projekt Firebase, jeśli jeszcze go nie masz.
   1. W konsoli Firebase kliknij Dodaj projekt i postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.

2. Przenieś projekt na abonament Blaze. Pozwala to utworzyć instancję Cloud SQL for PostgreSQL.

3. Przejdź do sekcji Data Connect w konsoli Firebase i postępuj zgodnie z procedurą konfiguracji usługi.

4. Wybierz lokalizację bazy danych CloudSQL for PostgreSQL.

5. Zapisz nazwy i identyfikatory projektów, usług i baz danych do późniejszego potwierdzenia.

6. Wykonaj pozostałe czynności konfiguracyjne i kliknij Gotowe.

Wybieranie i konfigurowanie środowiska programistycznego

Zaczniemy od Data Connect, od utworzenia prototypu aplikacji w kodzie w Visual Studio.

Opcjonalnie możesz zainstalować lokalną bazę danych PostgreSQL na potrzeby lokalnego programowania, używając emulatora Data Connect. Konfigurację omówiliśmy na końcu tego krótkiego przewodnika.

Data Connect obsługuje 2 etapy tworzenia prototypów:

• Jeśli jesteś programistą internetowym lub Kotlin Android, możesz tworzyć prototypy schematów i operacji lokalnie podczas łączenia się z instancją Cloud SQL for PostgreSQL lub (opcjonalnie) uruchamiać PostgreSQL lokalnie.

• Jeśli jesteś programistą internetowym, możesz użyć IDX do tworzenia prototypów w obszarze roboczym IDX za pomocą wstępnie skonfigurowanego szablonu IDX w PostgreSQL, rozszerzenia VS kodu z emulatorem Data Connect oraz skonfigurowanego za Ciebie kodu krótkiego wprowadzenia.

Konfigurowanie projektu lokalnego

Zainstaluj interfejs wiersza poleceń, postępując zgodnie z normalnymi instrukcjami.

Następnie włącz eksperyment Firebase Data Connect.

firebase experiments:enable dataconnect

Aby skonfigurować projekt lokalny, zainicjujemy katalog projektu i zaktualizujemy kilka plików konfiguracji potrzebnych do wygenerowania kodu.

Skonfiguruj katalog projektu

Zainicjuj katalog projektu.

Każda z tych procedur spowoduje utworzenie plików firebase.json i .firebaserc oraz podkatalogów (dataconnect), w tym ważnych plików dataconnect.yaml i connector.yaml w lokalnym katalogu roboczym.

Określ, gdzie jest generowany kod pakietu SDK

Data Connect automatycznie generuje kod pakietu SDK podczas edytowania schematu.

Aby określić, gdzie mają być generowane pakiety SDK, zaktualizuj plik początkowego oprogramowania sprzęgającego w: 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

Poznaj pakiet narzędzi Data Connect

Pakiet narzędzi Data Connect Toolkit jest komponentem rozszerzenia Firebase VS Code, który ułatwia tworzenie schematów oraz zarządzanie zapytaniami i mutacjami bezpośrednio z poziomu Visual Studio Code.

Aby przyjrzeć się funkcjom pakietu narzędzi:

1. Otwórz katalog projektu Firebase w narzędziu VS Code.
2. W panelu po lewej stronie w VS Code kliknij ikonę Firebase, aby otworzyć interfejs rozszerzenia Firebase VS Code.

W czasie programowania pamiętaj, że pakiet narzędzi umożliwia interakcję ze środowiskiem lokalnym oraz z zasobami produkcyjnymi. W tym krótkim wprowadzeniu nauczysz się korzystać ze środowiska produkcyjnego.

Interfejs rozszerzenia oferuje kilka przydatnych funkcji:

Na głównym pasku bocznym kodu VS Code:

Główny pasek boczny

• panel Konfiguracja, który pozwala zalogować się w Google i wybrać projekt Firebase.
• Panel Firebase Data Connect, który umożliwia sterowanie wbudowanym emulatorem i wdrażanie zasobów w środowisku produkcyjnym.
• panel Eksplorator FDC, który zawiera listę automatycznie wygenerowanych zapytań i mutacji wygenerowanych na podstawie schematu.

W dolnym panelu kodu VS Code:

Dolny panel

• Karta Data Connect Execution zawierająca narzędzia umożliwiające przekazywanie danych w żądaniach, symulowanie uwierzytelniania i wyświetlanie wyników.

Zanim zaczniemy tworzyć aplikację, zapoznaj się z niektórymi funkcjami rozszerzenia.

Tworzenie schematu i zapytania w Data Connect

Konfiguracja ukończona. Teraz możemy zacząć tworzyć aplikacje przy użyciu Data Connect.

Zacznij używać GraphQL do modelowania użytkowników i adresów e-mail. Aktualizujesz źródła za:

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

Zacznij tworzyć schemat

W katalogu projektu Firebase zwróć uwagę na folder dataconnect. Tutaj definiuje się model danych dla bazy danych Cloud SQL za pomocą GraphQL.

W pliku /dataconnect/schema/schema.gql zacznij definiować schemat obejmujący użytkowników i adresy e-mail.

Użytkownik

W Data Connect pola w GrafieQL są zmapowane na kolumny. Użytkownicy mają uid, name i adres e-mail address. Data Connect rozpoznaje kilka podstawowych typów danych: String i Date.

Skopiuj poniższy fragment kodu lub usuń znacznik komentarza z odpowiadających im wierszy w pliku.

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

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

Domyślnie Firebase Data Connect doda klucz UUID id, jeśli nie zostanie podany żaden klucz. W tym przypadku chcesz, aby kluczem podstawowym był mój uid. Możesz to zrobić za pomocą dyrektywy @table(key: "uid").

Wyślij e-mailem

Gdy masz już użytkowników, możesz tworzyć modele e-maili. Tutaj możesz dodać typowe pola (lub kolumny) danych poczty e-mail. Tym razem pominęliśmy dodawanie klucza podstawowego, ponieważ zarządzanie nim odbywa się za pomocą Data Connect.

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

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

Zwróć uwagę, że pole from jest zmapowane na typ User. Usługa Data Connect rozumie, że jest to relacja między Email a User, i będzie zarządzać tą relacją za Ciebie.

Wdrażanie schematu w środowisku produkcyjnym

Ponieważ używasz rozszerzenia Firebase VS Code do pracy z produkcyjną bazą danych, musisz wdrożyć schemat, zanim przejdziesz dalej.

1. Do wdrożenia możesz użyć rozszerzenia Firebase VS Code.
   • W interfejsie rozszerzenia w panelu Firebase Data Connect kliknij Wdróż.

2. Możesz też użyć interfejsu wiersza poleceń Firebase.

   firebase deploy
   

3. W przepływie rozszerzenia lub interfejsu wiersza poleceń może być konieczne sprawdzenie zmian schematu i zatwierdzenie potencjalnie szkodliwych modyfikacji. Zobaczysz te prośby:

   • Sprawdź zmiany schematu za pomocą polecenia firebase dataconnect:sql:diff
   • Jeśli zmiany są zadowalające, zastosuj je w ramach procesu, który uruchomił się przez firebase dataconnect:sql:migrate.

Zobacz wygenerowane rozszerzenia schematów

Podczas edytowania schematu e-maili usługa Data Connect automatycznie generuje rozszerzenia schematu, zapytania, mutacje, filtry i relacje w tabelach. Wygenerowany kod możesz wyświetlić na 2 sposoby.

• Listę wygenerowanych zapytań i mutacji niejawnych znajdziesz w interfejsie rozszerzenia Firebase w panelu Eksplorator FDC.
• Cały wygenerowany lokalnie kod możesz wyświetlić w źródłach w katalogu .dataconnect/schema.

Wykonaj mutację, aby dodać dane do tabeli

Przyciski CodeLens pojawiają się nad typami GraphQL w /dataconnect/schema/schema.gql.

Zapytania i mutacje w czasie programowania

Operacje powiązane z przyciskami CodeLens są szybkie i przydatne działania, w tym przypadku polegające na dodaniu danych do tabeli. Data Connect wykorzystuje mutacje GraphQL do opisania, jak i kto może działać na bazie danych. Użycie tego przycisku tworzy operację czasu programowania pozwalającą na szybkie generowanie danych.

Po wdrożeniu schematu w środowisku produkcyjnym możesz wykonywać te działania w backendzie za pomocą przycisków Uruchom (produkcja).

Utwórz zapytanie, aby wyświetlić listę adresów e-mail

Teraz najciekawsza część: zapytania. Jako programista masz przyzwyczajenie do pisania zapytań SQL niż w przypadku GraphQL, więc na początku może to wyglądać nieco inaczej. Jednak GraphQL jest o wiele bardziej skomplikowany i łatwiejszy do wpisywania niż nieprzetworzony SQL. Nasze rozszerzenie VS Code ułatwia programowanie.

Zacznij edytować plik /dataconnect/connector/queries.gql. Jeśli chcesz otrzymywać wszystkie e-maile, użyj zapytania podobnego do tego.

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

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

Bardzo ekscytującą cechą jest tutaj możliwość traktowania relacji z bazą danych jak wykresu. Adres e-mail zawiera pole from, które odwołuje się do użytkownika, możesz więc zagnieździć się w tym polu i z powrotem uzyskać informacje o użytkowniku.

Dyrektywa @auth

Dyrektywa @auth nie wykorzystuje w tym przykładzie swojego pełnego potencjału, ale sama koncepcja jest bardzo potężna. W ten sposób określasz zasadę autoryzacji operacji na bazie danych.

To zapytanie jest dość proste. Prawdziwe, fascynujące funkcje Data Connect stają się widoczne, gdy wykonujesz bardziej złożone złączania za pomocą relacji wiele do wielu. Więcej informacji na ten temat znajdziesz w trakcie zapoznawania się z narzędziami i dokumentacją.

Testowanie zapytania

Po utworzeniu tego zapytania sprawdź, czy działa, zanim przeprowadzisz integrację z kodem klienta. Jedną z funkcji dla programistów związanych z Data Connect jest możliwość szybkiego iterowania i testowania wyników zapytań za pomocą panelu Data Connect Execution.

Możesz podać argumenty, których potrzebuje to zapytanie, a następnie kliknąć przycisk CodeLens nad nazwą zapytania. Spowoduje to uruchomienie zapytania i wyświetlenie wyników.

Generowanie kodu pakietu SDK klienta i danych zapytań z aplikacji klienckiej

Aby zakończyć cykl programowania, zintegruj to zapytanie z kodem klienta.

Możesz napisać klienta, który zademonstruje wywoływanie zapytania i obsługę odpowiedzi z usługi Data Connect.

1. Zlokalizuj automatycznie wygenerowane źródła w lokalizacji określonej wcześniej w pliku connector.yaml.

2. Dodaj Firebase do swojego projektu, zarejestruj aplikację i zainstaluj odpowiedni podstawowy pakiet SDK Firebase:

   • W przypadku JavaScriptu wykonaj te instrukcje.
   • W przypadku Kotlin postępuj zgodnie z tymi instrukcjami.

3. Jeśli nie używasz IDX, możesz skonfigurować klienta, który można wywoływać z wiersza poleceń.

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

    node clientTest.js
    

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

Wdrażanie gotowego prototypu w środowisku produkcyjnym

Udało Ci się przeprowadzić iterację programową. Teraz możesz wdrożyć schemat, dane, zapytania i mutacje na serwerze za pomocą interfejsu użytkownika rozszerzenia Firebase lub interfejsu wiersza poleceń Firebase – tak samo jak w przypadku schematu.

Po wdrożeniu usługa Data Connect będzie gotowa do przetwarzania operacji klientów. Instancja Cloud SQL for PostgreSQL zostanie zaktualizowana o ostateczny wdrożony wygenerowany schemat i dane.

(Opcjonalnie) Instalowanie PostgreSQL lokalnie

Zainstalowanie PostgreSQL lokalnie i zintegrowanie go z emulatorem umożliwia tworzenie prototypów w w pełni lokalnym środowisku programistycznym.

Możesz zainstalować nową instancję PostgreSQL lub użyć istniejącej.

Zainstaluj PostgreSQL

Zainstaluj PostgreSQL w wersji 15.x, postępując zgodnie z instrukcjami dla swojej platformy.

• macOS Pobierz i zainstaluj Postgres.app.
• Windows: użyj instalatora EDB ze strony pobierania PostgreSQL.
• Docker: pobierz i uruchom obraz pgvector/pgvector:15, który obsługuje zarówno PostgreSQL 15.x, jak i obsługę wektorów.
• Linux: zalecamy korzystanie z Dockera z poprzednim obrazem, ale możesz też wykonać alternatywne instrukcje dotyczące popularnych dystrybucji.

Zapisz nazwę hosta, port, nazwę użytkownika i hasło oraz powiązane parametry podczas sekwencji instalacji.

Aby połączyć się z instancją PostgreSQL, emulator musi mieć:

• Te parametry konfiguracji
• Nazwa bazy danych z dataconnect.yaml i odpowiednio nazwana baza danych zainicjowana w Twojej instancji lokalnej.

Zaktualizuj .firebaserc za pomocą ciągu znaków połączenia

Użyj szczegółów lokalnej konfiguracji PostgreSQL, w tym nazwy użytkownika i hasła lokalnego PostgreSQL, aby uzyskać ciąg połączenia, który należy dodać do poniższego klucza w pliku .firebaserc.

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

Nawiązywanie połączenia z lokalną instancją PostgreSQL

Po wykonaniu tej konfiguracji możesz połączyć się z lokalną bazą danych:

1. W panelu po lewej stronie w VS Code kliknij ikonę Firebase, aby otworzyć interfejs rozszerzenia Firebase VS Code.
2. Kliknij przycisk Connect to Local PostgreSQL (Połącz z lokalnym PostgreSQL).

Dalsze kroki