Tài liệu tham khảo về lệnh CLI của Firebase cho Data Connect

Firebase CLI là một công cụ cho phép bạn quản lý và định cấu hình các sản phẩm và dịch vụ của Firebase thông qua dòng lệnh.

CLI cung cấp các lệnh có thể dùng để thực hiện nhiều tác vụ Data Connect, chẳng hạn như tạo dự án Data Connect mới, khởi chạy thư mục làm việc cục bộ tương ứng, thiết lập trình mô phỏng Data Connect, liệt kê tài nguyên Data Connect, tạo SDK ứng dụng và nhiều tác vụ khác.

Lệnh thiết lập

Thêm Data Connect vào một dự án Firebase

firebase init

Sử dụng firebase init để thiết lập một cấu hình dự án cục bộ mới. Quy trình này sẽ tạo hoặc cập nhật các tệp cấu hình Firebase trong thư mục của bạn.

firebase init

Quy trình firebase init hướng dẫn bạn thiết lập một dịch vụ và cơ sở dữ liệu, đồng thời cài đặt trình mô phỏng Data Connect và định cấu hình các SDK đã tạo (nếu muốn).

Thiết lập dịch vụ và cơ sở dữ liệu

Nếu bạn chọn dataconnect để thiết lập sản phẩm, thì CLI sẽ nhắc bạn nhập tên và vị trí dịch vụ mới, cũng như có liên kết một phiên bản Cloud SQL for PostgreSQL hiện có hay tạo một phiên bản mới.

Nếu một phiên bản hiện có được liên kết, thì CLI sẽ kiểm tra các chế độ cài đặt tương thích, chẳng hạn như xác thực IAM và địa chỉ IP công khai.

Thiết lập Local Emulator Suite

Quy trình CLI cung cấp các lựa chọn thiết lập trình mô phỏng, bao gồm cả trình mô phỏng Data Connect.

Lệnh trình mô phỏng Data Connect

Khởi động trình mô phỏng Data Connect

emulators:start/exec

firebase emulators:start/exec

Sử dụng phiên bản Local Emulator Suite của trình mô phỏng Data Connect ở chế độ tương tác với start hoặc chế độ không tương tác dựa trên tập lệnh với exec.

Xuất và nhập dữ liệu PostgreSQL cục bộ

Để hỗ trợ việc tạo mẫu và kiểm thử cục bộ, cũng như tích hợp liên tục, bạn có thể xuất dữ liệu được lưu trữ trong một thực thể cơ sở dữ liệu cục bộ và nhập dữ liệu đó giữa các lần lặp lại quá trình phát triển và các lần chạy kiểm thử.

Dữ liệu xuất được lưu trữ dưới dạng ảnh chụp nhanh của cơ sở dữ liệu PostgreSQL cục bộ.

Data Connect cung cấp 3 cách để xuất/nhập:

  • Tính năng tự động xuất/nhập được định cấu hình trong firebase.json để cung cấp các bản sao lưu ảnh chụp nhanh khi trình mô phỏng tắt và khởi động
  • Xuất/nhập theo cách thủ công bằng CLI
  • Xuất/nhập theo cách thủ công bằng giao diện tiện ích VS Code

Đã định cấu hình tính năng tự động xuất và nhập trong firebase.json

Để sao lưu dữ liệu giữa các phiên phát triển, hãy chỉ định một vị trí sao lưu tự động trong trình tự firebase init. Vị trí này được lưu trữ trong firebase.json của bạn trong trường emulators.dataconnect.dataDir. Mọi thay đổi về dữ liệu mà bạn thực hiện sẽ tự động được lưu ở đây giữa các lần chạy trình mô phỏng, vì vậy, điều này rất hữu ích trong quá trình kiểm thử và khám phá cục bộ.

Xuất theo cách thủ công: emulators:export và emulators:start/exec --import

Trong khi trình mô phỏng Data Connect đang chạy, trong một thiết bị đầu cuối riêng biệt, hãy chạy lệnh firebase emulators:export để lưu ảnh chụp nhanh dữ liệu của bạn. Sau đó, bạn có thể khởi động trình mô phỏng từ ảnh chụp nhanh đó bằng cách sử dụng cờ --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>

Xuất/nhập thủ công: Tiện ích VS Code

Trong giao diện người dùng của tiện ích VS Code, trong khi trình mô phỏng đang chạy, hãy dùng nút Xuất dữ liệu trình mô phỏng để xuất dữ liệu nhằm xuất nội dung cơ sở dữ liệu hiện tại. Vị trí xuất mặc định là thư mục exportedData ở gốc của thư mục dự án.

Bạn có thể nhập dữ liệu này bằng CLI, như mô tả trong phần trước. Bạn cũng có thể nhập dữ liệu này trước khi khởi động trình mô phỏng thông qua VS Code bằng cách nhấp vào đường liên kết Định cấu hình trình mô phỏng và đặt Đường dẫn nhập.

Các lệnh quản lý giản đồ và trình kết nối

Phần này chứa thông tin tham khảo về CLI cho các lệnh mà bạn dùng để quản lý lược đồ và trình kết nối.

Để biết các trường hợp sử dụng và các phương pháp được đề xuất liên quan đến những lệnh này, hãy xem hướng dẫn quản lý lược đồ và trình kết nối.

Triển khai giản đồ và trình kết nối

triển khai

firebase deploy

Lệnh này triển khai các tài nguyên cho các dịch vụ Data Connect được lập chỉ mục trong firebase.json. Quá trình di chuyển giản đồ và cập nhật trình kết nối sẽ được thực hiện nếu cần.

Lệnh Nội dung mô tả

firebase deploy

Cờ Nội dung mô tả

--only dataconnect

Triển khai giản đồ và trình kết nối cho tất cả các dịch vụ Data Connect cho dự án này, nhưng không triển khai các tài nguyên sản phẩm khác của Firebase.

--only dataconnect:serviceId

Triển khai giản đồ và trình kết nối cho dịch vụ Trình kết nối dữ liệu đã chỉ định.

--only dataconnect:serviceId:connectorId

Triển khai một trình kết nối cho Dịch vụ kết nối dữ liệu được chỉ định.

–-only dataconnect:serviceId:schema

Triển khai giản đồ cho dịch vụ Data Connect được chỉ định.

Với cờ –-only, bạn có thể truyền các giá trị được phân tách bằng dấu phẩy để triển khai bất kỳ tập hợp con nào của tài nguyên mà bạn muốn.

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

Liệt kê các dịch vụ, giản đồ và trình kết nối Data Connect

dataconnect:services:list

firebase dataconnect:services:list

Lệnh này in thông tin cơ bản về các dịch vụ, giản đồ và trình kết nối được triển khai trên một dự án.

So sánh và di chuyển giản đồ SQL

Khi bạn chạy firebase deploy, CLI sẽ thực hiện so sánh giản đồ SQL trước khi triển khai các bản cập nhật. Bạn cũng có thể thực hiện việc so sánh và cập nhật trực tiếp bằng một bộ lệnh dataconnect:sql.

dataconnect:sql:diff

firebase dataconnect:sql:diff

Lệnh này so sánh giản đồ cục bộ của một dịch vụ với giản đồ hiện tại của cơ sở dữ liệu Cloud SQL tương ứng. Thao tác này sẽ in ra các lệnh sẽ được chạy để di chuyển cơ sở dữ liệu sang giản đồ mới.

Lệnh Nội dung mô tả

firebase dataconnect:sql:diff

Cờ/Tham số Nội dung mô tả

serviceId

Chỉ định dịch vụ. Nếu bỏ qua, hãy in chênh lệch cho tất cả các dịch vụ trong firebase.json.

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

Lệnh này áp dụng các thay đổi về giản đồ cục bộ cho cơ sở dữ liệu Cloud SQL của một dịch vụ.

Khi bạn thiết lập một dự án Data Connect cục bộ mới bằng tệp dataconnect.yaml mặc định, hành vi của lệnh dataconnect:sql:migrate là nhắc bạn thực hiện mọi thay đổi bắt buộc, sau đó nhắc bạn thực hiện mọi thay đổi không bắt buộc trước khi thực hiện các thay đổi. Bạn có thể sửa đổi hành vi này để luôn bao gồm hoặc bỏ qua các thay đổi không bắt buộc bằng cách cập nhật cấu hình dataconnect.yaml, như đã thảo luận trong phần di chuyển giản đồ ở chế độ nghiêm ngặt hoặc tương thích

Trong môi trường tương tác, CLI sẽ hiển thị từng câu lệnh SQL di chuyển (và liệu câu lệnh đó có gây lỗi hay không) rồi nhắc bạn về những thay đổi mà bạn muốn áp dụng. Truyền cờ --force tương đương với việc chấp nhận tất cả các lời nhắc.

Trong môi trường không tương tác:

  • Nếu không có --force, chỉ những thay đổi không làm ảnh hưởng đến dữ liệu gốc mới được thực hiện. Nếu có các thay đổi mang tính huỷ diệt, thì CLI sẽ huỷ bỏ mà không thực hiện thay đổi nào.
  • Với --force, mọi thay đổi đều được thực hiện. Nếu có bất kỳ thay đổi nào mang tính huỷ diệt, thì những thay đổi đó sẽ được in và bạn sẽ được nhắc xem bạn có muốn tiếp tục hay không, trừ phi bạn cung cấp cờ --force.
Lệnh Nội dung mô tả

firebase dataconnect:sql:migrate

Cờ Nội dung mô tả

serviceId

Di chuyển cơ sở dữ liệu cho dịch vụ được chỉ định. serviceId được suy luận nếu dự án của bạn chỉ có một dịch vụ.

--force

Tự động chấp nhận câu lệnh.

Giống như các cờ --only khác, bạn có thể cung cấp nhiều dịch vụ được phân tách bằng dấu phẩy.

Di chuyển giản đồ ở chế độ nghiêm ngặt hoặc chế độ tương thích

Quá trình di chuyển giản đồ Data Connect có 2 chế độ xác thực giản đồ khác nhau: strict (nghiêm ngặt) và compatible (tương thích). Quy trình xác thực ở chế độ nghiêm ngặt yêu cầu lược đồ cơ sở dữ liệu phải khớp chính xác với lược đồ ứng dụng trước khi có thể triển khai lược đồ ứng dụng. Xác thực chế độ tương thích yêu cầu giản đồ cơ sở dữ liệu phải tương thích với giản đồ ứng dụng, tức là các phần tử trong cơ sở dữ liệu mà giản đồ ứng dụng không dùng đến sẽ không bị sửa đổi.

Các chế độ xác thực giản đồ và phương pháp hay nhất để di chuyển giản đồ này được đề cập trong hướng dẫn quản lý giản đồ và trình kết nối

Chế độ xác thực được xác định bằng khoá schemaValidation trong tệp dataconnect.yaml. Nếu bạn không chỉ định schemaValidation, thì CLI sẽ áp dụng các thay đổi tương thích và nhắc bạn trước khi thực hiện bất kỳ thay đổi nghiêm ngặt nào. Xem tài liệu tham khảo về cấu hình.

Quản lý các thay đổi đối với trình kết nối

Khi bạn chạy firebase deploy, CLI sẽ bắt đầu cập nhật các trình kết nối hiện hành. CLI phân tích các thay đổi đối với từng trình kết nối và đưa ra một bộ thông báo đánh giá liên quan đến những thay đổi của trình kết nối có thể gây ra hành vi không mong muốn (thông báo ở cấp cảnh báo) hoặc sự cố (thông báo ở cấp độ lỗi) trong các phiên bản trước của mã ứng dụng.

Đánh giá tác động Trường hợp
Cấp độ cảnh báo (tương thích với dây, có thể thay đổi hành vi)
  • Xoá một trường có thể rỗng khỏi truy vấn mà không có chú thích @retired.
Mức độ thay đổi lớn (không tương thích với wire, có thể làm hỏng ứng dụng)
  • Thay đổi một biến có thể rỗng thành không rỗng mà không có giá trị mặc định.
  • Thay đổi kiểu dữ liệu của một trường thành kiểu dữ liệu tương thích với JSON (ví dụ: Int thành Float).
  • Thay đổi một cột không rỗng thành cột có thể rỗng.
  • Xoá một biến có thể rỗng mà không có chú thích @retired.
  • Xoá một biến không rỗng có giá trị mặc định mà không có chú thích @retired.
Cấp độ thay đổi lớn (không tương thích với dây, sẽ làm hỏng ứng dụng)
  • Xoá một thao tác mà không có chú thích @retired.
  • Xoá một trường không rỗng khỏi truy vấn mà không có chú thích @retired.
  • Thêm một biến không rỗng mà không có giá trị mặc định.
  • Thay đổi loại dữ liệu của một trường thành loại dữ liệu không tương thích (ví dụ: String thành Int).
  • Xoá một biến không rỗng mà không có giá trị mặc định và không có chú thích @retired.

Trong môi trường tương tác, CLI sẽ hiển thị từng đánh giá về trình kết nối và nhắc bạn về những thay đổi mà bạn muốn áp dụng. Việc truyền cờ --force tương đương với việc chấp nhận tất cả các bài đánh giá.

Trong môi trường không tương tác:

  • nếu chỉ có các đánh giá ở cấp cảnh báo (có thể có thay đổi về hành vi), thì tất cả các trình kết nối sẽ được triển khai và cảnh báo sẽ được ghi vào thiết bị đầu cuối.
  • nếu có bất kỳ đánh giá nào ở cấp độ phá vỡ, thì sẽ không có trình kết nối nào được triển khai và cảnh báo sẽ được ghi vào thiết bị đầu cuối. Bạn có thể ghi đè bằng cờ --force.

Kiểm tra mã uỷ quyền

Data Connect giúp bạn kiểm tra chiến lược uỷ quyền bằng cách phân tích mã trình kết nối khi bạn triển khai lên máy chủ bằng firebase deploy từ CLI Firebase. Bạn có thể sử dụng quy trình kiểm tra này để xem xét cơ sở mã của mình.

Khi bạn triển khai các trình kết nối, CLI sẽ đưa ra các đánh giá về mã thao tác hiện có, đã sửa đổi và mới trong trình kết nối của bạn.

Đối với các thao tác đã sửa đổi và thao tác mới, CLI sẽ đưa ra cảnh báo và nhắc bạn xác nhận khi bạn sử dụng một số cấp truy cập nhất định trong các thao tác mới hoặc khi bạn sửa đổi các thao tác hiện có để sử dụng các cấp truy cập đó.

Cảnh báo và lời nhắc luôn xuất hiện trong các trường hợp sau:

  • PUBLIC

Ngoài ra, cảnh báo và lời nhắc sẽ xuất hiện ở các cấp truy cập sau đây khi bạn không tăng cường các cấp truy cập này bằng bộ lọc thông qua auth.uid:

  • USER
  • USER_ANON
  • USER_EMAIL_VERIFIED

Để biết thêm thông tin về việc uỷ quyền, hãy tham khảo hướng dẫn về việc uỷ quyền và chứng thực.

Lệnh SDK

Tạo SDK

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

Lệnh này tạo ra các SDK được nhập khai báo trong connector.yaml.

Bạn cũng có thể xem hướng dẫn về cách sử dụng các SDK web, các SDK Android và các SDK iOS.

Lệnh Nội dung mô tả

firebase dataconnect:sdk:generate

Cờ Nội dung mô tả

–-watch

Duy trì quá trình chạy và tạo SDK mới bất cứ khi nào bạn lưu các thay đổi đối với tệp GQL lược đồ và trình kết nối.

Nếu quá trình tạo không thành công, các lỗi sẽ được in ra stdout, mã được tạo sẽ không thay đổi và lệnh sẽ tiếp tục chạy.

--only connectorId:platform

Chỉ tạo SDK cho một nền tảng và một trình kết nối.

Với cờ –only, bạn có thể truyền các giá trị được phân tách bằng dấu phẩy.

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

Lệnh quản lý Cloud SQL

Cấp vai trò SQL cho Cloud SQL

Data Connect hoạt động trên phiên bản PostgreSQL của riêng bạn được lưu trữ trên Cloud SQL. Các lệnh vai trò SQL giúp bạn quản lý quyền trên các bảng cơ sở dữ liệu.

dataconnect:sql:setup

firebase dataconnect:sql:setup

Lệnh này định cấu hình các quyền ban đầu, toàn cục đối với các bảng trong cơ sở dữ liệu của bạn.

Quy trình quản lý và cung cấp cơ sở dữ liệu mặc định giả định rằng dự án của bạn sử dụng một cơ sở dữ liệu mới (chưa có gì), và khi bạn gọi firebase deploy, Data Connect sẽ hiển thị các thay đổi về giản đồ cơ sở dữ liệu cần thực hiện và thực hiện mọi hoạt động di chuyển sau khi bạn phê duyệt. Nếu đây là quy trình bạn muốn, dataconnect:sql:setup sẽ nhắc bạn cấp các quyền, bao gồm cả quyền sở hữu lược đồ superuser.

Đối với các cơ sở dữ liệu hiện có (brownfield), bạn có thể có quy trình làm việc riêng để di chuyển giản đồ và muốn tự duy trì quyền sở hữu giản đồ. Nếu đây là quy trình bạn muốn, hãy nhớ từ chối tại lời nhắc dataconnect:sql:setup về việc Data Connect có nên xử lý việc di chuyển SQL cho bạn hay không. Do bạn từ chối, Data Connect sẽ chỉ có quyền truy cập read và write vào các bảng trong cơ sở dữ liệu của bạn, nhưng bạn vẫn phải chịu trách nhiệm về quyền sở hữu và việc di chuyển giản đồ.

Để biết thêm thông tin thảo luận và các trường hợp sử dụng, hãy xem phần Quản lý các dịch vụ và cơ sở dữ liệu.

dataconnect:sql:grant

firebase dataconnect:sql:grant

Trong một số trường hợp, bạn có thể muốn truy cập trực tiếp vào cơ sở dữ liệu của mình để truy vấn hoặc cập nhật dữ liệu do các ứng dụng Data Connect tạo ra. Để làm việc này, bạn sẽ cần cấp một trong các vai trò được xác định trong phần này cho người dùng hoặc tài khoản dịch vụ cần thiết.

Để biết thông tin chi tiết về các vai trò được cấp, hãy xem phần Vai trò người dùng PostgreSQL.

Vai trò Vai trò SQL Quyền Cách sử dụng Có thể cấp
reader firebasereader_<db_name>_<schema_name> Quyền chỉ đọc đối với cơ sở dữ liệu.

Có thể thực hiện các thao tác SELECT trên tất cả các bảng trong giản đồ được chỉ định.		 Lý tưởng cho người dùng hoặc dịch vụ yêu cầu truy xuất dữ liệu nhưng không sửa đổi dữ liệu. Có
writer firebasewriter_<db_name>_<schema_name> Quyền đọc và ghi vào cơ sở dữ liệu.

Có thể thực hiện các thao tác SELECT, INSERT, UPDATE, DELETE và TRUNCATE trên tất cả các bảng trong giản đồ.		 Phù hợp với những người dùng hoặc dịch vụ cần sửa đổi dữ liệu trong cơ sở dữ liệu. Có
chủ sở hữu firebaseowner_<db_name>_<schema_name> Chủ sở hữu giản đồ.

Có tất cả các đặc quyền trên mọi bảng và chuỗi trong giản đồ.		 Vai trò này, kết hợp với vai trò IAM roles/cloudsql.client, cấp quyền thực hiện quy trình di chuyển trên cơ sở dữ liệu.

Ví dụ: khi gọi firebase dataconnect:sql:migrate.		 Có
siêu người dùng cloudsqlsuperuser Vai trò người dùng cấp cao tích hợp sẵn với đầy đủ đặc quyền trên cơ sở dữ liệu.

Ngoài các quyền của chủ sở hữu, vai trò này có thể tạo giản đồ, xoá giản đồ, cài đặt tiện ích và thực hiện mọi tác vụ quản trị khác.

Được truy cập trong CLI bằng cách đăng nhập với tư cách là "firebasesuperuser".		 Bắt buộc để cài đặt các tiện ích, tạo lược đồ ban đầu và cấp bất kỳ vai trò SQL nào có thể cấp cho người dùng khác.

Nếu người dùng không phải quản trị viên cần đặc quyền của siêu người dùng, thì quá trình di chuyển sẽ không thành công và nhắc người dùng yêu cầu quản trị viên cơ sở dữ liệu (tức là người dùng có roles/cloudsql.admin) chạy các lệnh SQL có đặc quyền.		 Được cấp cho người dùng có roles/cloudsql.admin và không thể cấp trực tiếp từ CLI Firebase
Lệnh Nội dung mô tả

firebase dataconnect:sql:grant

Cờ/Tham số Nội dung mô tả

-R, --role role

Vai trò SQL cần cấp, một trong các vai trò: chủ sở hữu, người viết hoặc người đọc.

-E, --email email_address

Email của người dùng hoặc tài khoản dịch vụ để cấp vai trò.

Lựa chọn chung

Các lựa chọn chung sau đây áp dụng cho tất cả các lệnh:

  • --json chuyển đầu ra CLI sang JSON để các công cụ khác phân tích cú pháp.
  • Ghi đè --noninteractive và --interactive (nếu cần), tự động phát hiện các môi trường không phải TTY.