Bắt đầu sử dụng Firebase Data Connect

Trong phần hướng dẫn bắt đầu nhanh này, bạn sẽ tìm hiểu cách:

  • Thêm Firebase Data Connect vào dự án Firebase của bạn.
  • Thiết lập một môi trường phát triển, bao gồm cả tiện ích Mã Visual Studio để hoạt động với một phiên bản phát hành chính thức.
  • Sau đó, chúng tôi sẽ hướng dẫn bạn cách:
    • Tạo giản đồ bằng ví dụ về ứng dụng email.
    • Xác định truy vấn và trường hợp biến đổi cho giản đồ của bạn.
    • Sử dụng SDK được tạo tự động để gọi các truy vấn và biến đổi này từ ứng dụng.
    • Triển khai nguyên mẫu cuối cùng trong quá trình sản xuất.

Điều kiện tiên quyết

Để sử dụng tính năng khởi động nhanh này, bạn sẽ cần những yếu tố sau.

Thêm Data Connect vào dự án của bạn và tạo nguồn dữ liệu

  1. Hãy tạo một dự án Firebase nếu bạn chưa có.
    1. Trong bảng điều khiển của Firebase, hãy nhấp vào Thêm dự án, sau đó làm theo hướng dẫn trên màn hình.

  2. Nâng cấp dự án của bạn lên gói linh hoạt. Điều này cho phép bạn tạo một phiên bản Cloud SQL cho phiên bản PostgreSQL.

  3. Chuyển đến mục Data Connect (Kết nối dữ liệu) trên bảng điều khiển của Firebase và làm theo quy trình thiết lập sản phẩm.

  4. Chọn vị trí cho cơ sở dữ liệu CloudSQL cho PostgreSQL.

  5. Hãy ghi lại tên cũng như mã nhận dạng của dự án, dịch vụ và cơ sở dữ liệu để xác nhận sau.

  6. Làm theo quy trình thiết lập còn lại, sau đó nhấp vào Xong.

Chọn và thiết lập môi trường phát triển

Bạn sẽ bắt đầu với Data Connect bằng cách tạo nguyên mẫu cho một ứng dụng trong Mã Visual Studio.

Bạn có thể tuỳ ý cài đặt cơ sở dữ liệu PostgreSQL cục bộ để phát triển cục bộ bằng trình mô phỏng Data Connect. Quy trình thiết lập này sẽ được đề cập ở cuối hướng dẫn bắt đầu nhanh này.

Data Connect hỗ trợ hai trải nghiệm phát triển để tạo nguyên mẫu:

  • Nếu là nhà phát triển web hoặc Kotlin Android, bạn có thể tạo nguyên mẫu và hoạt động trên máy trong khi kết nối với phiên bản Cloud SQL cho PostgreSQL hoặc (không bắt buộc) chạy PostgreSQL cục bộ.

  • Nếu là nhà phát triển web, bạn có thể sử dụng IDX để tạo nguyên mẫu trong không gian làm việc IDX bằng cách sử dụng một mẫu IDX được định cấu hình sẵn với PostgreSQL, phần mở rộng mã VS với trình mô phỏng Data Connect và thiết lập mã bắt đầu nhanh cho bạn.

Phát triển mã VS

Nếu bạn muốn phát triển cục bộ thay vì sử dụng IDX, hãy thiết lập tiện ích Mã Firebase VS để giúp bạn nhanh chóng lặp lại quá trình phát triển bằng cách tạo SDK cho web, Kotlin Android và sắp ra mắt cho iOS.

  1. Tạo thư mục mới cho dự án cục bộ.
  2. Mở Mã VS trong thư mục mới.
  3. Tải tiện ích này xuống, đóng gói dưới dạng gói VSIX, từ Firebase Storage.
  4. Trong VS Code, trên trình đơn View (Chế độ xem), hãy chọn Extensions (Tiện ích).
  5. Trên thanh tiêu đề của bảng điều khiển Tiện ích, hãy nhấp vào biểu tượng trình đơn more_horiz, sau đó làm theo Cài đặt từ VSIX....

Phát triển IDX

IDX là môi trường được tối ưu hóa để phát triển ứng dụng web. Nếu bạn là nhà phát triển Kotlin Android, hãy làm theo các bước trên thẻ Phát triển mã VS.

Cách thiết lập một mẫu Data Connect IDX:

  1. Truy cập vào mẫu tại trang web của Project IDX.
  2. Làm theo quy trình thiết lập.

Thiết lập dự án cục bộ

Cài đặt CLI theo hướng dẫn thông thường.

Sau đó, hãy bật thử nghiệm Firebase Data Connect.

firebase experiments:enable dataconnect

Để thiết lập dự án cục bộ cho bạn, chúng tôi sẽ khởi chạy thư mục dự án và cập nhật một số tệp cấu hình cần thiết cho việc tạo mã.

Thiết lập thư mục dự án

Khởi động thư mục dự án của bạn.

Thiết lập tiện ích Firebase

Trong bảng điều khiển bên trái Mã VS, hãy nhấp vào biểu tượng Firebase để mở giao diện người dùng tiện ích Mã VS Firebase.

Trong giao diện người dùng tiện ích Firebase:

  1. Hãy đảm bảo rằng bạn đã đăng nhập.
  2. Trong bảng điều khiển của Firebase, hãy xác nhận rằng quy trình thiết lập Data Connect, bao gồm cả việc cấp phép cơ sở dữ liệu, đã hoàn tất.
  3. Nhấp vào nút Run firebase init (Chạy firebase init).
  4. Xem thẻ Terminal (Thiết bị đầu cuối) trong bảng điều khiển VS Code dưới để xem các lời nhắc.
  5. Chọn Kết nối dữ liệu làm tính năng để sử dụng trong thư mục này.
  6. Khi được nhắc, hãy cung cấp mã dự án, dịch vụ và cơ sở dữ liệu của dự án Data Connect mà bạn đã tạo trước đó trong bảng điều khiển.

Thiết lập nhà ga

  1. Nếu cần, hãy đăng nhập bằng firebase login.
  2. Trong bảng điều khiển của Firebase, hãy xác nhận rằng quy trình thiết lập Data Connect, bao gồm cả việc cấp phép cơ sở dữ liệu, đã hoàn tất.
  3. Chạy firebase init để khởi chạy thư mục của bạn dưới dạng một dự án Firebase, theo lời nhắc trên màn hình.
  4. Chọn Kết nối dữ liệu làm tính năng để sử dụng trong thư mục này.
  5. Khi được nhắc, hãy cung cấp mã dự án, dịch vụ và cơ sở dữ liệu của dự án Data Connect mà bạn đã tạo trước đó trong bảng điều khiển.

Một trong hai flow sẽ tạo một tệp firebase.json và .firebaserc và các thư mục con dataconnect bao gồm các tệp dataconnect.yaml và connector.yaml quan trọng trong thư mục đang làm việc cục bộ của bạn.

Định cấu hình nơi tạo mã SDK

Data Connect tự động tạo mã SDK trong khi bạn chỉnh sửa giản đồ của mình.

Để chỉ định nơi tạo SDK, hãy cập nhật tệp cho trình kết nối ban đầu trong 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

Làm quen với Bộ công cụ Data Connect

Data Connect Toolkit là một thành phần của tiện ích Mã VS Firebase giúp phát triển giản đồ cũng như quản lý truy vấn và biến đổi, trực tiếp từ Visual Studio Code.

Để xem các tính năng của Bộ công cụ:

  1. Mở thư mục dự án Firebase trong VS Code (nếu bạn chưa thực hiện).
  2. Trong mã VS, trong bảng điều khiển bên trái, hãy nhấp vào biểu tượng Firebase để mở giao diện người dùng của phần mở rộng về mã VS.

Trong suốt quá trình phát triển, xin lưu ý rằng Bộ công cụ này cho phép bạn tương tác với môi trường địa phương cũng như với các tài nguyên sản xuất. Trong phần hướng dẫn bắt đầu nhanh này, bạn sẽ tương tác với môi trường sản xuất.

Tiện ích mã VS cho Data Connect trong IDX

Giao diện người dùng tiện ích cung cấp cho bạn một số tính năng hữu ích:

Trong thanh bên chính của mã VS:

  • Bảng điều khiển Config (Cấu hình), cho phép bạn đăng nhập vào Google và chọn một dự án Firebase.
  • Bảng điều khiển Firebase Data Connect (Kết nối dữ liệu của Firebase) cho phép bạn kiểm soát trình mô phỏng tích hợp và triển khai tài nguyên cho giai đoạn phát hành chính thức.
  • Bảng điều khiển FDC Explorer (Trình khám phá FDC) liệt kê các truy vấn ngầm ẩn và các biến đổi được tạo tự động dựa trên giản đồ của bạn
Trong bảng điều khiển thấp hơn Mã VS:

  • Thẻ Data Connect Execution (Thực thi kết nối dữ liệu) có các công cụ cho phép bạn truyền dữ liệu theo yêu cầu, bắt chước quy trình xác thực và xem kết quả.

Trước khi chúng ta bắt đầu phát triển một ứng dụng, hãy xem một số tính năng của tiện ích này.

Dùng thử CodeLens tuỳ chỉnh Khi bạn làm việc với các tài nguyên trong các tệp schema.gql, queries.gql và mutations.gql, sau khi bạn đã viết các khối mã có cú pháp hoàn chỉnh, một CodeLens tuỳ chỉnh sẽ hiển thị các thao tác bạn có thể thực hiện trên các bảng và thao tác đã khai báo.
  • Đối với bảng, CodeLens giúp bạn tạo các đột biến để thêm dữ liệu vào cơ sở dữ liệu phụ trợ.
  • Đối với các truy vấn và trường hợp biến đổi, CodeLens cho phép bạn chạy các thao tác trên máy hoặc dựa trên tài nguyên phát hành công khai.
Đặt cấp xác thực cho các yêu cầu Trong bảng điều khiển dưới, bảng điều khiển Thực thi kết nối dữ liệu cung cấp thẻ Cấu hình để bạn có thể chọn các cấp xác thực được mô phỏng cho các thao tác.
Điền các biến vào truy vấn và biến đổi Trong cùng thẻ Cấu hình, bạn có thể điền sẵn các tải trọng hoạt động.
Kiểm tra nhật ký, phản hồi và lỗi Ngoài ra, trong thẻ Cấu hình, bạn có thể xem thẻ Nhật ký và Kết quả để biết thông tin gỡ lỗi.

Tạo giản đồ và truy vấn Data Connect

Bạn đã thiết lập xong. Giờ đây, chúng ta có thể bắt đầu phát triển bằng Data Connect.

Bắt đầu sử dụng GraphQL để lập mô hình người dùng và email. Bạn sẽ cập nhật các nguồn tin trong:

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

Bắt đầu phát triển một giản đồ

Trong thư mục dự án Firebase, hãy để ý thư mục dataconnect. Đây là nơi bạn xác định mô hình dữ liệu cho cơ sở dữ liệu Cloud SQL bằng GraphQL.

Trong tệp /dataconnect/schema/schema.gql, hãy bắt đầu xác định một giản đồ bao gồm người dùng và email.

Người dùng

Trong Data Connect, các trường GraphQL được liên kết với các cột. Người dùng có uid, name và email address. Data Connect nhận dạng một số kiểu dữ liệu gốc: String và Date.

Sao chép đoạn mã sau đây hoặc huỷ nhận xét về các dòng tương ứng trong tệp.

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

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

Theo mặc định, Firebase Data Connect sẽ thêm khoá UUID id nếu chưa có khoá nào được cung cấp. Tuy nhiên, trong trường hợp này, bạn muốn uid của tôi là khoá chính. Bạn có thể thực hiện việc này thông qua lệnh @table(key: "uid").

Email

Giờ đây khi đã có người dùng, bạn có thể lập mô hình email. Tại đây, bạn có thể thêm các trường (hoặc cột) điển hình cho dữ liệu email. Lần này, chúng ta bỏ qua việc thêm khoá chính vì bạn có thể dựa vào Data Connect để quản lý khoá.

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

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

Xin lưu ý rằng trường from được liên kết với một loại User. Data Connect hiểu rằng đây là mối quan hệ giữa Email và User và sẽ quản lý mối quan hệ này cho bạn.

Triển khai giản đồ trong môi trường thực tế

Vì đang sử dụng tiện ích Mã VS Firebase để làm việc với cơ sở dữ liệu chính thức, nên bạn cần triển khai giản đồ trước khi tiếp tục.

  1. Bạn có thể sử dụng phần mở rộng về mã Firebase VS để triển khai.
    • Trong giao diện người dùng tiện ích, trong bảng điều khiển Firebase Data Connect, hãy nhấp vào Deploy (Triển khai).

  2. Ngoài ra, bạn có thể sử dụng Giao diện dòng lệnh (CLI) của Firebase.

    firebase deploy

  3. Trong quy trình của tiện ích hoặc quy trình CLI, bạn có thể cần phải xem xét các thay đổi giản đồ và phê duyệt những nội dung sửa đổi có thể phá hoại. Bạn sẽ thấy lời nhắc:

    • Xem các thay đổi giản đồ bằng firebase dataconnect:sql:diff
    • Khi bạn đã hài lòng với các thay đổi, hãy áp dụng các thay đổi đó bằng cách sử dụng luồng do firebase dataconnect:sql:migrate bắt đầu.

Xem phần mở rộng giản đồ đã tạo

Khi bạn chỉnh sửa giản đồ email, Data Connect sẽ tự động tạo phần mở rộng giản đồ, truy vấn, biến đổi, bộ lọc và mối quan hệ với bảng. Bạn có thể xem mã đã tạo này theo 2 cách.

  • Bạn có thể xem danh sách các truy vấn ngầm ẩn và các biến đổi đã tạo trong giao diện người dùng tiện ích Firebase, trong bảng điều khiển FDC Explorer (Trình khám phá FDC).
  • Bạn có thể xem tất cả các mã được tạo cục bộ ở các nguồn trong thư mục .dataconnect/schema.

Thực hiện thay đổi để thêm dữ liệu vào bảng của bạn

Bạn có thể thấy các nút CodeLens xuất hiện trên các loại GraphQL trong /dataconnect/schema/schema.gql.

Đột biến và truy vấn thời gian phát triển

Các thao tác liên kết với các nút CodeLens này là những thao tác nhanh chóng và hữu ích, trong trường hợp này là thêm dữ liệu vào bảng. Data Connect sử dụng các đột biến GraphQL để mô tả cách thức và đối tượng có thể thao tác dựa trên cơ sở dữ liệu. Khi sử dụng nút này, nút này sẽ tạo một thao tác thời gian phát triển để gieo hạt dữ liệu nhanh chóng.

Sau khi triển khai giản đồ trong phiên bản chính thức, bạn có thể sử dụng các nút CodeLens Chạy (Bản chính thức) để thực hiện các thao tác này trên phần phụ trợ.

Viết truy vấn để liệt kê các email

Phần thú vị là truy vấn. Là nhà phát triển, bạn đã quen với việc viết truy vấn SQL thay vì truy vấn GraphQL, vì vậy, lúc đầu bạn có thể cảm thấy hơi khác. Tuy nhiên, GraphQL ngắn gọn và an toàn về loại hơn nhiều so với SQL thô. Và tiện ích VS Code của chúng tôi giúp đơn giản hoá trải nghiệm phát triển.

Bắt đầu chỉnh sửa tệp /dataconnect/connector/queries.gql. Nếu bạn muốn nhận tất cả email, hãy sử dụng một truy vấn như thế này.

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

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

Một tính năng thực sự thú vị ở đây là khả năng xử lý các mối quan hệ của cơ sở dữ liệu như một biểu đồ. Vì một Email có trường from tham chiếu đến một Người dùng, nên bạn có thể lồng vào trường này và nhận lại thông tin về người dùng.

lệnh @auth

Trong ví dụ này, lệnh @auth chưa được khai thác hết tiềm năng nhưng khái niệm này thực sự hiệu quả. Đây là cách bạn quyết định chính sách uỷ quyền cho các thao tác dựa trên cơ sở dữ liệu.

Truy vấn này khá đơn giản, các tính năng thú vị thực sự của Data Connect bắt đầu nổi bật khi bạn thực hiện các phép liên kết phức tạp hơn với mối quan hệ nhiều với nhiều. Bạn sẽ tìm hiểu thêm về điều này trong quá trình khám phá các công cụ và tài liệu.

Kiểm tra truy vấn của bạn

Bây giờ, chúng ta đã tạo truy vấn này, hãy kiểm tra xem truy vấn có hoạt động hay không trước khi tích hợp truy vấn vào mã ứng dụng. Một phần trong trải nghiệm của nhà phát triển đối với Data Connect là khả năng lặp lại và kiểm thử nhanh kết quả truy vấn bằng bảng điều khiển Data Connect Execution (Thực thi kết nối dữ liệu).

Bạn có thể cung cấp các đối số mà truy vấn này cần, sau đó nhấp vào nút CodeLens phía trên tên truy vấn. Thao tác này sẽ thực thi truy vấn và hiển thị kết quả để bạn có thể thấy rằng truy vấn đang hoạt động như mong đợi.

Tạo mã SDK ứng dụng và dữ liệu truy vấn từ một ứng dụng khách

Để kết thúc chu trình phát triển, hãy tích hợp truy vấn này vào mã ứng dụng.

Bạn có thể viết ứng dụng khách để minh hoạ cách gọi truy vấn và xử lý các phản hồi từ dịch vụ Data Connect.

  1. Xác định vị trí các nguồn được tạo tự động tại vị trí mà bạn đã chỉ định trước đó trong tệp connector.yaml.

  2. Thêm Firebase vào dự án của bạn, đăng ký ứng dụng và cài đặt SDK cốt lõi Firebase có liên quan:

  3. Nếu không sử dụng IDX, bạn có thể thiết lập một ứng dụng có thể gọi qua dòng lệnh.

JavaScript

Tạo một tệp nguồn clientTest.js rồi sao chép mã sau.

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

Và bạn có thể chạy ứng dụng của mình.

    node clientTest.js
Kotlin cho Android

Tạo một tệp nguồn clientTest.kt rồi sao chép mã sau.

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

Sau đó:

  1. Chạy Hoạt động.
  2. Kiểm tra đầu ra logcat của Android.

Đưa nguyên mẫu đã hoàn thành vào môi trường thực tế

Bạn đã trải qua một vòng lặp phát triển. Giờ đây, bạn có thể triển khai giản đồ, dữ liệu, truy vấn và các biến đổi cho máy chủ bằng giao diện người dùng tiện ích Firebase hoặc Firebase CLI của Firebase, giống như cách bạn đã thực hiện với giản đồ.

Sau khi được triển khai, dịch vụ Data Connect của bạn sẽ sẵn sàng để xử lý hoạt động của khách hàng. Phiên bản Cloud SQL cho PostgreSQL sẽ được cập nhật với giản đồ và dữ liệu đã tạo đã triển khai cuối cùng.

(Không bắt buộc) Cài đặt PostgreSQL cục bộ

Việc cài đặt PostgreSQL cục bộ và tích hợp với trình mô phỏng cho phép bạn tạo mẫu trong môi trường phát triển hoàn toàn cục bộ.

Bạn có thể cài đặt một phiên bản PostgreSQL mới hoặc dùng một phiên bản hiện có.

Cài đặt PostgreSQL

Cài đặt PostgreSQL phiên bản 15.x theo hướng dẫn dành cho nền tảng của bạn.

Lưu ý tên máy chủ, cổng, tên người dùng và mật khẩu cũng như các tham số liên quan đầu ra trong quá trình cài đặt.

Để kết nối với phiên bản PostgreSQL, trình mô phỏng cần có:

  • Các thông số cấu hình thiết lập này
  • Tên cơ sở dữ liệu từ dataconnect.yaml và cơ sở dữ liệu được đặt tên tương ứng được khởi tạo trong thực thể cục bộ của bạn.

Cập nhật .firebaserc bằng chuỗi kết nối

Sử dụng thông tin chi tiết về cấu hình PostgreSQL cục bộ, bao gồm cả tên người dùng và mật khẩu PostgreSQL cục bộ để thêm chuỗi kết nối vào khoá sau trong tệp .firebaserc.

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

Kết nối với phiên bản PostgreSQL cục bộ

Sau khi cấu hình xong, để kết nối với cơ sở dữ liệu cục bộ, hãy làm như sau:

  1. Trong mã VS, trong bảng điều khiển bên trái, hãy nhấp vào biểu tượng Firebase để mở giao diện người dùng của phần mở rộng về mã VS.
  2. Nhấp vào nút Kết nối với PostgreSQL cục bộ.

Các bước tiếp theo