Tiện ích Google Cloud Firestore

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X.
thông tin

Phiên bản: 1.4.1

Tạo, đọc hoặc xoá dữ liệu trong cơ sở dữ liệu Cloud Firestore.

Nội dung này cung cấp tài liệu tham khảo để định cấu hình và sử dụng tiện ích này. Trước khi sử dụng tiện ích này từ proxy API, bạn phải:

  1. Tạo một dự án Firebase tại bảng điều khiển của Firebase để lưu trữ dữ liệu của bạn.

  2. Tạo khoá cho tài khoản dịch vụ.

  3. Sử dụng nội dung của tệp JSON chứa khoá thu được khi thêm và định cấu hình tiện ích bằng cách sử dụng tài liệu tham khảo về cấu hình.

Giới thiệu về Cloud Firestore

Cloud Firestore lưu trữ dữ liệu trong tài liệu, được lưu trữ trong các bộ sưu tập. Cloud Firestore tạo các bộ sưu tập và tài liệu một cách ngầm ẩn trong lần đầu tiên bạn thêm dữ liệu vào tài liệu. Bạn không cần phải tạo bộ sưu tập hoặc tài liệu một cách rõ ràng.

Để biết thêm thông tin về Cloud Firestore nói chung, hãy xem phần Bắt đầu sử dụng Firestore trong tài liệu về Cloud Firestore.

Mẫu

Ví dụ sau minh hoạ cách định cấu hình tính năng hỗ trợ các hành động đối với phần mở rộng của Cloud Firestore bằng Chính sách về phần mở rộng.

Thêm dữ liệu

Chính sách Chú thích tiện ích sau đây thêm một tài liệu có tên là freewill@example.com vào bộ sưu tập users. Thuộc tính data chỉ định các trường và giá trị của tài liệu mới.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Add-User-Data">
    <DisplayName>Add User Data</DisplayName>
    <Connector>my-cloud-firestore-extension</Connector>
    <Action>setDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "freewill@example.com",
        "data" : {
            "firstName": "Will",
            "lastName": "Witman",
            "address": "270-8243 Tempor St.",
            "city": "Fort Worth",
            "region": "TX",
            "postalCode": "86519",
            "email": "freewill@example.com",
            "username": "freewill444"
        }
    }]]></Input>
</ConnectorCallout>

Lấy dữ liệu

Trong ví dụ này, Chính sách Chú thích tiện ích truy xuất giá trị của tài liệu freewill@example.com từ bộ sưu tập users. Ở đây, thuộc tính parsed của phần tử <Output> được thiết lập thành false để kết quả trả về sẽ có định dạng JSON dưới dạng chuỗi, thay vì JSON được phân tích cú pháp thành một đối tượng. Để biết thêm thông tin, hãy xem tài liệu tham khảo về phần tử <Output>.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Get-User-Data">
    <DisplayName>Get User Data</DisplayName>
    <Connector>straut-cloud-firestore-extension</Connector>
    <Action>getDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "freewill@example.com"
    }]]></Input>
    <Output parsed="false">firestore.userdata.retrieved</Output>
</ConnectorCallout>

Chính sách Chỉ định thông báo sau đây sử dụng giá trị của biến lưu trữ phản hồi của tiện ích để chỉ định tải trọng phản hồi.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage name="CopyUserDataToResponse">
    <DisplayName>Copy User Data To Response</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{firestore.userdata.retrieved}</Payload>
    </Set>
</AssignMessage>

Xoá dữ liệu

Trong ví dụ này, Chính sách chú thích tiện ích sẽ xoá tài liệu lizzie@example.com khỏi bộ sưu tập users.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Delete-User-Data">
    <DisplayName>Delete User Data</DisplayName>
    <Connector>my-cloud-firestore-extension</Connector>
    <Action>deleteDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "lizzie@example.com"
    }]]></Input>
</ConnectorCallout>

Dữ liệu truy vấn

Trong ví dụ này, Chính sách chú thích tiện ích truy vấn một tập hợp cities. Kết quả truy vấn được lọc theo các trường statepopulation. Ở đây, thuộc tính parsed của phần tử <Output> được thiết lập thành false để kết quả trả về sẽ có định dạng JSON dưới dạng chuỗi, thay vì JSON được phân tích cú pháp thành một đối tượng. Để biết thêm thông tin, hãy xem tài liệu tham khảo về phần tử <Output>.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Query-City-Data">
    <DisplayName>Query City Data</DisplayName>
    <Connector>cloud-firestore-extension</Connector>
    <Action>query</Action>
    <Input><![CDATA[{
        "colName":"cities",
        "queryArray":[
          ["state", "==", "CA"],
          ["population","<",1000000]
        ]
    }]]></Input>
    <Output parsed="false">compound-query-output</Output>
</ConnectorCallout>

Chính sách Chỉ định thông báo sau đây sử dụng giá trị của biến lưu trữ phản hồi của tiện ích để chỉ định tải trọng phản hồi.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage name="CopyQueryResultsToResponse">
    <DisplayName>Copy Query Results To Response</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{firestore.querydata.retrieved}</Payload>
    </Set>
</AssignMessage>

Thao tác

deleteDocument

Xoá một tài liệu khỏi bộ sưu tập.

Thông số yêu cầu

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>
Thông số Nội dung mô tả Loại Mặc định Bắt buộc
colName Tên của bộ sưu tập có chứa tài liệu cần xoá. Chuỗi Không nội dung nào. Có.
docName Tên của tài liệu cần xoá. Chuỗi Không nội dung nào. Có.

Phản hồi

Không nội dung nào.

getDocument

Truy xuất nội dung của một tài liệu.

Thông số yêu cầu

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>
Thông số Nội dung mô tả Loại Mặc định Bắt buộc
colName Tên của bộ sưu tập để truy xuất tài liệu. Chuỗi Không nội dung nào. Có.
docName Tên của tài liệu cần truy xuất. Chuỗi Không nội dung nào. Có.

Phản hồi

Đối tượng chứa nội dung của tài liệu ở định dạng JSON.

query

Truy vấn một tập hợp bằng cách chỉ định các điều kiện tạo thành bộ lọc.

Tham số queryArray của hành động này chỉ định một mảng gồm các mảng (hoặc một mảng trống nếu không có điều kiện lọc). Mỗi mảng bên trong chỉ định một điều kiện của bộ lọc. Nhiều mảng bên trong biểu thị nhiều điều kiện được kết hợp bằng toán tử AND.

Mỗi phần tử trong một mảng điều kiện bên trong đại diện cho một phần của điều kiện đó. Một mảng điều kiện luôn có 3 phần tử sau đây:

  • Phần tử bên trái xác định trường bộ sưu tập.
  • Phần tử ở giữa chỉ định toán tử.
  • Phần tử bên phải xác định giá trị của trường bộ sưu tập.

Ví dụ sau đây chỉ định 2 mảng điều kiện cần lọc dựa trên các trường statepopulation của bộ sưu tập:

<Input><![CDATA[{
  "colName":"cities",
  "queryArray":[
    ["state", "==", "CA"],
    ["population","<",1000000]
  ]
}]]></Input>

Trong thời gian chạy, hành động này được hiểu là một truy vấn chẳng hạn như sau:

Chọn tất cả thành phố có tiểu bang = "CA" và dân số < 1000000

Một truy vấn bao gồm nhiều điều kiện phải được hỗ trợ trong Cloud Firestore bằng một chỉ mục tổng hợp. Để biết thêm thông tin, hãy xem phần Các loại chỉ mục trong Cloud Firestore.

Thông số yêu cầu

Cú pháp

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "queryArray" : "queryArray": query-condition-array
}]]></Input>

Ví dụ:

Trong ví dụ này, tham số queryArray chỉ định 2 điều kiện để lọc tập hợp cities do tham số colName chỉ định.

Một truy vấn bao gồm nhiều điều kiện phải được hỗ trợ trong Cloud Firestore bằng một chỉ mục tổng hợp. Để biết thêm thông tin, hãy xem phần Các loại chỉ mục trong Cloud Firestore.

<Input><![CDATA[{
  "colName":"cities",
  "queryArray":[["state", "==", "CA"],["population","<",1000000]]
}]]></Input>

Trong thời gian chạy, hành động này được hiểu là một truy vấn chẳng hạn như sau:

Chọn tất cả thành phố có tiểu bang = "CA" và dân số < 1000000

Thông số Nội dung mô tả Loại Mặc định Bắt buộc
colName Tên của tập hợp để truy vấn. Chuỗi Không nội dung nào. Có.
queryArray Một mảng gồm các mảng điều kiện cùng nhau chỉ định các phần của bộ lọc. Hãy chỉ định một mảng trống để bỏ qua điều kiện (không lọc kết quả). Mảng Không nội dung nào. Có.

Phản hồi

Đối tượng chứa nội dung của tài liệu ở định dạng JSON.

setDocument

Sao chép tài liệu vào bộ sưu tập Cloud Firestore. Nếu tài liệu đã tồn tại trong bộ sưu tập, tài liệu này sẽ ghi đè lên tài liệu.

Thông số yêu cầu

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name",
  "data" : "data-to-copy"
}]]></Input>
Thông số Nội dung mô tả Loại Mặc định Bắt buộc
colName Tên của bộ sưu tập mà bạn dùng để tạo tài liệu. Chuỗi Không nội dung nào. Có.
docName Tên của tài liệu cần sao chép data. Chuỗi Không nội dung nào. Có.
data Dữ liệu cần sao chép vào docName. Đây phải là đối tượng JSON hợp lệ. Mảng không được hỗ trợ. Đối tượng Không nội dung nào. Không.

Phản hồi

Không nội dung nào.

Tài liệu tham khảo về cấu hình

Sử dụng các đoạn mã sau khi bạn định cấu hình và triển khai tiện ích này để sử dụng trong các proxy API. Để biết các bước định cấu hình một tiện ích bằng bảng điều khiển Apigee, hãy xem bài viết Thêm và định cấu hình tiện ích.

Thuộc tính tiện ích phổ biến

Các thuộc tính sau có sẵn cho mỗi tiện ích.

Tài sản Mô tả Mặc định Bắt buộc
name Tên mà bạn đang đặt cho cấu hình của tiện ích này. Không có
packageName Tên của gói tiện ích do Apigee Edge cung cấp. Không có
version Số phiên bản của gói tiện ích mà bạn đang định cấu hình tiện ích. Không có
configuration Giá trị cấu hình cụ thể cho tiện ích bạn đang thêm. Xem Thuộc tính cho gói tiện ích này Không có

Các thuộc tính cho gói tiện ích này

Tài sản Nội dung mô tả Mặc định Bắt buộc
firestoreDB URL tới cơ sở dữ liệu Cloud Firestore mà tiện ích này sẽ sử dụng khi gửi yêu cầu. URL này thường có dạng https://DATABASE_NAME.firebaseio.com. Không nội dung nào. Có.
thông tin xác thực Khi được nhập vào bảng điều khiển của Apigee Edge, đây là nội dung của tệp khoá mà bạn đã tạo theo hướng dẫn của Firebase. Khi được gửi qua API quản lý, giá trị này là giá trị được mã hoá base64 từ tệp khoá. Không nội dung nào. Có.