Dokumentacja poleceń interfejsu wiersza poleceń Firebase dla Data Connect

Interfejs wiersza poleceń Firebase to narzędzie, które umożliwia zarządzanie usługami i usługami Firebase oraz ich konfigurowanie z wiersza poleceń.

Interfejs wiersza poleceń udostępnia polecenia, których można używać do wykonywania różnych Data Connectzadań, takich jak tworzenie nowego projektu Data Connect, inicjowanie odpowiedniego lokalnego katalogu roboczego, konfigurowanie emulatora Data Connect, wyświetlanie zasobów Data Connect, generowanie pakietów SDK klienta itp.

Polecenia konfiguracji

Dodawanie aplikacji Data Connect do projektu Firebase

firebase init

Aby skonfigurować nową konfigurację projektu lokalnego, użyj polecenia firebase init. Ten proces tworzy lub aktualizuje pliki konfiguracji Firebase w Twoim katalogu.

firebase init

Proces firebase init poprowadzi Cię przez konfigurowanie usługi i bazy danych oraz opcjonalnie przez instalowanie emulatora Data Connect i konfigurowanie wygenerowanych pakietów SDK.

Konfiguracja usługi i bazy danych

Jeśli wybierzesz dataconnect w przypadku konfiguracji usługi, interfejs wiersza poleceń poprosi Cię o podanie nazwy i lokalizacji nowej usługi oraz o to, czy chcesz połączyć istniejące wystąpienie Cloud SQL for PostgreSQL, czy utworzyć nowe.

Jeśli połączona jest istniejąca instancja, interfejs wiersza poleceń sprawdza, czy istnieją kompatybilne ustawienia, takie jak uwierzytelnianie IAM i publiczne adresy IP.

Local Emulator Suite konfiguracja

Interfejs wiersza poleceń umożliwia konfigurowanie emulatorów, w tym emulatora Data Connect.

Data Connect polecenia emulatora

Uruchom emulator Data Connect

emulatory:start/exec

firebase emulators:start/exec

Użyj wersji Local Emulator Suite emulatora Data Connect w trybie interaktywnym (start) lub w trybie nieinteraktywnym (exec) sterowanym przez skrypt.

Eksportowanie i importowanie lokalnych danych PostgreSQL

Aby umożliwić prototypowanie i testowanie lokalne oraz ciągłą integrację, możesz eksportować dane zapisane w lokalnym wystąpieniu bazy danych i importować je między iteracjami rozwoju i przeprowadzeniem testów.

Dane eksportowane są jako zrzuty dysków lokalnej bazy danych PostgreSQL.

Data Connect oferuje 3 metody eksportowania/importowania:

  • automatycznego eksportowania/importowania skonfigurowanego w firebase.json, aby tworzyć kopie zapasowe migawek podczas zamykania i uruchamiania emulatora;
  • Ręczny eksport/import za pomocą interfejsu wiersza poleceń
  • Ręczny eksport i import za pomocą interfejsu rozszerzenia VS Code

automatyczny eksport i import skonfigurowany w Twoim firebase.json.

Aby tworzyć kopie zapasowe danych między sesjami programowania, określ automatyczną lokalizację kopii zapasowej podczas sekwencji firebase init. Ta lokalizacja jest przechowywana w Twoim pliku firebase.json w polu emulators.dataconnect.dataDir. Wszystkie zmiany danych zostaną automatycznie zapisane tutaj między uruchomieniami emulatora, więc jest to przydatne podczas testowania i eksplorowania lokalnie.

Eksport ręczny: emulators:export i emulators:start/exec --import

Gdy emulowany system Data Connect jest uruchomiony, w oddzielnym terminalu uruchom polecenie firebase emulators:export, aby zapisać migawkę danych. Następnie możesz uruchomić emulator z tego migawka za pomocą flagi --import.

# Export data from local emulator from a separate terminal
firebase emulators:export --only dataconnect <export_directory>

# Import data from local directory, here using emulators:exec
firebase emulators:exec ./<your-test-script>.sh --only dataconnect --import <import_directory>

Ręczny eksport/import: rozszerzenie VS Code

Gdy emulator jest uruchomiony, w interfejsie rozszerzenia VS Code kliknij przycisk Eksportuj dane emulatora, aby wyeksportować bieżącą zawartość bazy danych. Domyślna lokalizacja eksportu to katalog exportedData w katalogu głównym katalogu projektu.

Możesz importować te dane za pomocą interfejsu wiersza poleceń, zgodnie z opisem w poprzedniej sekcji. Możesz też zaimportować te dane przed uruchomieniem emulatora w VS Code, klikając link Konfiguruj emulator i ustawiając Ścieżka importu.

Polecenia zarządzania schematami i połączeniami

Ta sekcja zawiera informacje o poleceniach interfejsu wiersza poleceń, których używasz do zarządzania schemami i złączami.

Informacje o przypadkach użycia i zalecanych metodach związanych z tymi poleceniami znajdziesz w przewodniku Schemat i sprzęganie.

Wdrażanie schematów i oprogramowania sprzęgającego

wdróż

firebase deploy

To polecenie wdraża zasoby usług Data Connect powiązane z plikiem firebase.json. W razie potrzeby wykonywana jest migracja schematu i aktualizacja oprogramowania sprzęgającego.

Command Opis

firebase deploy

Flaga Opis

–-only dataconnect

Wdrożyć schematy i złącza dla wszystkich usług Data Connect w tym projekcie, ale nie wdrażać innych zasobów usług Firebase.

–-only dataconnect:serviceId

Wdrażanie schematu i złączników w przypadku wybranej usługi Data Connect.

–-only dataconnect:serviceId:connectorId

Wdrażanie pojedynczego łącznika na potrzeby określonej usługi Data Connect.

–-only dataconnect:serviceId:schema

Wdróż schemat dla określonej usługi Data Connect.

Dzięki flagom –-only możesz przekazywać wartości rozdzielone przecinkami, aby wdrożyć dowolny podzbiór zasobów.

firebase deploy --only dataconnect:service1:schema,dataconnect:service2

Wyświetlanie listy usług, schematów i złączeń Data Connect

dataconnect:services:list

firebase dataconnect:services:list

To polecenie wyświetla podstawowe informacje o usługach, schematach i złączach wdrożonych w projekcie.

Porównywanie i migracja schematów SQL

Gdy uruchomisz polecenie firebase deploy, interfejs wiersza poleceń przed wdrożeniem aktualizacji porównuje schemat SQL. Możesz też przeprowadzić porównanie i wprowadzić zmiany bezpośrednio za pomocą zestawu poleceń dataconnect:sql.

dataconnect:sql:diff

firebase dataconnect:sql:diff

To polecenie porównuje schemat lokalny usługi ze schematem bieżącym odpowiedniej bazy danych Cloud SQL. Wypisuje polecenia, które zostaną wykonane, aby przenieść bazę danych do nowego schematu.

Command Opis

firebase dataconnect:sql:diff

Flaga/parametr Opis

serviceId

Określ usługę. Jeśli nie zostanie podany, wydrukuje się różnica między wszystkimi usługami w pliku firebase.json.

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

To polecenie stosuje lokalne zmiany schematu do bazy danych Cloud SQL usługi.

Gdy skonfigurujesz nowy lokalny projekt Data Connect za pomocą domyślnego pliku dataconnect.yaml, polecenie dataconnect:sql:migrate będzie wyświetlać prompty dotyczące wprowadzania zmian wymaganych i opcjonalnych, a dopiero potem będzie je wykonywać. Możesz zmienić to zachowanie, aby zawsze uwzględniać lub ignorować opcjonalne zmiany, aktualizując konfigurację dataconnect.yaml, zgodnie z opisem w artykule Przenoszenie schematu w trybie ścisłym lub zgodnym.

W środowiskach interaktywnych interfejs wiersza poleceń wyświetla każde instrukcja SQL migracji (oraz informacje o tym, czy jest ona destruktywna) i prosi o wprowadzenie zmian, które chcesz zastosować. Przekazanie flagi --force jest równoznaczne z akceptacją wszystkich monitów.

W nieinteraktywnych środowiskach:

  • Bez --force wprowadzane są tylko zmiany nieniszczące. Jeśli występują zmiany, które mogą spowodować utratę danych, interfejs CLI jest przerywany bez wprowadzania zmian.
  • W przypadku opcji --force wszystkie zmiany zostaną wprowadzone. Jeśli obejmuje to zmiany, które mogą spowodować utratę danych, są one drukowane i wyświetla się pytanie, czy chcesz kontynuować. Wyjątek stanowi flaga --force.
Command Opis

firebase dataconnect:sql:migrate

Flaga Opis

serviceId

Przenieść bazę danych dla określonej usługi. serviceId jest wywnioskowany, jeśli projekt ma tylko jedną usługę.

–-force

automatycznie akceptować prompty;

Podobnie jak w przypadku innych oznaczeń --only, możesz podać wiele usług rozdzielonych przecinkami.

Migracja schematu w trybie rygorystycznym lub zgodnym

Migracje schematu Data Connect mają 2 różne tryby sprawdzania poprawności schematu: ścisły i zgodny. Walidacja w rygorystycznym trybie wymaga, aby schemat bazy danych dokładnie odpowiadał schematowi aplikacji, zanim schemat aplikacji zostanie wdrożony. Weryfikacja w trybie zgodności wymaga, aby schemat bazy danych był zgodny ze schematem aplikacji. Oznacza to, że elementy w bazie danych, których nie używa schemat aplikacji, pozostają niezmodyfikowane.

Te tryby sprawdzania schematu i sprawdzone metody migracji schematu znajdziesz w przewodniku po zarządzaniu schematami i łącznikami.

Tryb sprawdzania jest definiowany za pomocą klucza schemaValidation w pliku dataconnect.yaml. Jeśli parametr schemaValidation nie jest określony, interfejs wiersza poleceń stosuje zgodne zmiany i wyświetla prompt przed wykonaniem ścisłych zmian. Zobacz dokumentację konfiguracji.

Zarządzanie zmianami w sprzęgach

Gdy uruchomisz polecenie firebase deploy, interfejs wiersza poleceń rozpocznie aktualizację odpowiednich połączeń. CLI analizuje zmiany w każdym z połączeń i wysyła zestaw komunikatów oceny dotyczących zmian w połączeniu, które mogą powodować nieoczekiwane działanie (komunikaty są na poziomie ostrzeżenia) lub przerwy (komunikaty są na poziomie przerwy) w wcześniejszych wersjach kodu klienta.

Ocena wpływu Scenariusz
Poziom ostrzegawczy (zgodny z standardem, może zmieniać działanie)
  • usunięcie z zapytania pola z wartością dozwoloną null bez adnotacji @retired.
Zmiana zasadnicza (niezgodność z przewodami, może spowodować przerwanie działania klientów)
  • zmiana zmiennej z możliwością przyjęcia wartości null na nie-null bez wartości domyślnej;
  • Zmiana typu danych pola na zgodny z formatem JSON (np. Int na Float).
  • Zmiana kolumny niepustej na kolumnę dopuszczającą wartość null.
  • Usuwanie zmiennej z wartością dozwoloną bez adnotacji @retired.
  • Usuwanie zmiennej innej niż null o wartości domyślnej bez adnotacji @retired.
Zmiany na poziomie funkcji (niezgodność z protokołem, spowoduje przerwanie działania klientów)
  • Usuwanie operacji bez adnotacji @retired.
  • Usuwanie z zapytania pola niezerowego bez adnotacji @retired.
  • Dodanie zmiennej innej niż null bez wartości domyślnej.
  • zmiana typu danych pola na niezgodny (np. z String na Int).
  • Usuwanie zmiennej innej niż null bez wartości domyślnej i bez adnotacji @retired.

W środowiskach interaktywnych interfejs wiersza poleceń wyświetla ocenę każdego łącznika i wyświetla prompty dotyczące zmian, które chcesz wprowadzić. Przekazanie flagi --force jest równoznaczne z zaakceptowaniem wszystkich ocen.

W nieinterakcyjnych środowiskach:

  • jeśli występują tylko oceny na poziomie ostrzeżenia (możliwe zmiany zachowania), wszystkie złącza zostaną wdrożone, a ostrzeżenia zostaną zapisane w terminalu.
  • Jeśli wystąpią oceny na poziomie naruszenia, żadne złącza nie zostaną wdrożone, a ostrzeżenia zostaną zapisane w terminalu. Możesz zastąpić go flagą --force.

Kod autoryzacji do celów audytu

Data Connect pomaga Ci sprawdzić strategię autoryzacji. Analizuje ona kod łącznika podczas wdrażania na serwer za pomocą polecenia firebase deploy w pliku Firebase CLI. Możesz użyć tego audytu, aby sprawdzić kod źródłowy.

Podczas wdrażania usług połączonych interfejs wiersza poleceń generuje oceny dla istniejącego, zmodyfikowanego i nowego kodu operacji w połączeniu.

W przypadku zmodyfikowanych i nowych operacji interfejs wiersza poleceń wyświetla ostrzeżenia i wymaga potwierdzenia, gdy używasz określonych poziomów dostępu w nowych operacjach lub gdy modyfikujesz istniejące operacje, aby używać tych poziomów dostępu.

Ostrzeżenia i komunikaty zawsze pojawiają się w przypadku:

  • PUBLIC

Ostrzeżenia i komunikaty wyświetlają się na tych poziomach dostępu, gdy nie rozszerzysz ich za pomocą filtrów za pomocą auth.uid:

  • USER
  • USER_ANON
  • USER_EMAIL_VERIFIED

Więcej informacji o autoryzacji znajdziesz w przewodniku dotyczącym autoryzacji i poświadczenia.

Polecenia pakietu SDK

Generowanie pakietów SDK

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

To polecenie generuje typowane pakiety SDK zadeklarowane w pliku connector.yaml.

Zapoznaj się też z przewodnikami dotyczącymi pakietów SDK na potrzeby witryn internetowych, pakietów SDK na Androida i pakietów SDK na iOS.

Command Opis

firebase dataconnect:sdk:generate

Flaga Opis

–-watch

Utrzymuje proces i generuje nowe pakiety SDK za każdym razem, gdy zapiszesz zmiany w plikach GQL schematu i złącza.

Jeśli generowanie się nie powiedzie, błędy zostaną wydrukowane na wyjściu standardowym, wygenerowany kod nie ulegnie zmianie, a polecenie będzie nadal działać.

–-only connectorId:platform

generować pakiety SDK tylko dla jednej platformy i jednego łącznika,

Flagi –only umożliwiają przekazywanie wartości rozdzielonych przecinkami.

firebase dataconnect:sdk:generate –-only connector1, connector1:kotlin

Polecenia zarządzania Cloud SQL

Przypisywanie ról SQL w Cloud SQL

Data Connect działa na Twojej własnej instancji PostgreSQL hostowanej w Cloud SQL. Polecenia roli SQL pomagają zarządzać uprawnieniami do tabel bazy danych.

dataconnect:sql:setup

firebase dataconnect:sql:setup

To polecenie konfiguruje początkowe, globalne uprawnienia do tabel w Twojej bazie danych.

Domyślny proces tworzenia i zarządzania bazą danych zakłada, że Twój projekt korzysta z nowej bazy danych (tzw. greenfield). Gdy wywołasz firebase deploy, Data Connect wyświetli zmiany schematu bazy danych, które należy wprowadzić, a po Twojej akceptacji przeprowadzi migrację. Jeśli wolisz tę opcję, dataconnect:sql:setup poprosi Cię o przyznanie uprawnień, w tym uprawnień do superuser własności schema.

W przypadku istniejących baz danych (brownfield) możesz mieć własny proces migracji schematów i chcesz zachować własność schematu. Jeśli wolisz tę metodę, odrzuć prośbę dataconnect:sql:setup o to, czy Data Connect ma przeprowadzić migrację SQL za Ciebie. W efekcie odrzucenia Data Connect będzie mieć dostęp tylko do tabel bazy danych read i write, ale za własność schematu oraz migracje będziesz odpowiadać Ty.

Więcej informacji o dyskusji i przypadkach użycia znajdziesz w artykule Zarządzanie usługami i bazami danych.

dataconnect:sql:grant

firebase dataconnect:sql:grant

W niektórych przypadkach możesz chcieć uzyskać bezpośredni dostęp do bazy danych, aby wysłać zapytanie lub zaktualizować dane wygenerowane przez aplikacje Data Connect. Aby to zrobić, musisz przypisać jednemu z użytkowników lub kont usługi jedną z ról z tej sekcji.

Szczegółowe informacje o przyznanych rolach znajdziesz w artykule Role użytkownika PostgreSQL.

Rola Rola SQL Uprawnienia Wykorzystanie Grantable
reader firebasereader_<db_name>_<schema_name> Dostęp tylko do odczytu do bazy danych.

Może wykonywać operacje SELECT na wszystkich tabelach w ramach określonego schematu.		 To idealne rozwiązanie w przypadku użytkowników lub usług, które wymagają pobierania danych, ale nie ich modyfikacji. Tak
zapisujący firebasewriter_<db_name>_<schema_name> Uprawnienia do odczytu i zapisu do bazy danych.

Możesz wykonywać operacje SELECT, INSERT, UPDATE, DELETE i TRUNCATE na wszystkich tabelach w schemacie.		 Nadaje się do użytkowników lub usług, które muszą modyfikować dane w bazie danych. Tak
właściciel firebaseowner_<db_name>_<schema_name> Właściciel schematu.

 Ma wszystkie uprawnienia do wszystkich tabel i sekwencji w schemacie.		 Ta rola w połączeniu z rolą uprawnień roles/cloudsql.client przyznaje uprawnienia do migracji bazy danych.

Na przykład podczas dzwonienia do firebase dataconnect:sql:migrate.		 Tak
administrator | superużytkownik | root cloudsqlsuperuser Wbudowana rola superużytkownika z pełnymi uprawnieniami do bazy danych.

Oprócz uprawnień właściciela może tworzyć i usuwać schematy, instalować rozszerzenia i wykonywać inne zadania administracyjne.

Dostęp do niego w CLI uzyskujesz, logując się jako „firebasesuperuser”.		 Wymagane do instalowania rozszerzeń, tworzenia początkowego schematu i przyznawania innym użytkownikom dowolnych ról SQL.

Jeśli użytkownik, który nie jest administratorem, potrzebuje uprawnień superużytkownika, migracja zakończy się niepowodzeniem, a użytkownik zostanie poproszony o poproszenie administratora bazy danych (czyli użytkownika z uprawnieniami roles/cloudsql.admin), aby ten uruchomił polecenia SQL z uprawnieniami.		 Przyznawane użytkownikom z uprawnieniami roles/cloudsql.admin i nie można ich przyznać bezpośrednio z poziomu wiersza poleceń Firebase
Command Opis

firebase dataconnect:sql:grant

Flaga/parametr Opis

-R, --role role

Rola SQL do przyznania: właściciel, zapisujący lub odczytujący.

-E, --email email_address

Adres e-mail użytkownika lub konta usługi, któremu chcesz przypisać rolę.

Opcje globalne

Do wszystkich poleceń mają zastosowanie te opcje globalne:

  • --json przełącza dane wyjściowe CLI na format JSON do analizowania przez inne narzędzia.
  • W razie potrzeby --noninteractive i --interactive zastąpią automatyczne wykrywanie środowisk innych niż TTY.