Tiện ích Google Cloud Firestore

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. Thông tin

Phiên bản: 2.0.2

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 thông tin 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ừ một proxy API, bạn phải:

Tạo một dự án Firebase trong bảng điều khiển của Firebase, nơi lưu trữ dữ liệu của bạn.
Tạo khoá cho tài khoản dịch vụ.
Sử dụng nội dung của tệp JSON 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 các tài liệu được lưu trữ trong các tập hợp. Cloud Firestore sẽ tạo các bộ sưu tập và tài liệu một cách ngầm định vào lần đầu tiên bạn thêm dữ liệu vào tài liệu. Bạn không cần tạo rõ ràng các tập hợp hoặc tài liệu.

Để 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

Các ví dụ sau đây minh hoạ cách định cấu hình chế độ hỗ trợ cho các thao tác của tiện ích Cloud Firestore bằng cách sử dụng chính sách ExtensionCallout.

Thêm dữ liệu

Chính sách ExtensionCallout sau đây sẽ thêm một tài liệu có tên là freewill@example.com vào một 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 ExtensionCallout truy xuất giá trị của tài liệu freewill@example.com từ tập hợp users. Ở đây, thuộc tính parsed của phần tử <Output> được đặt thành false để kết quả trả về sẽ là JSON dưới dạng một 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 Assign Message (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 ExtensionCallout 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>

Truy vấn dữ liệu

Trong ví dụ này, chính sách ExtensionCallout truy vấn một tập hợp cities. Kết quả truy vấn được lọc theo các trường state và population. Ở đây, thuộc tính parsed của phần tử <Output> được đặt thành false để kết quả trả về sẽ là JSON dưới dạng một 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 Assign Message (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 một bộ sưu tập.

Tham số yêu cầu

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>

Tham số	Mô tả	Loại	Mặc định	Bắt buộc
colName	Tên của bộ sưu tập chứa tài liệu cần xoá.	Chuỗi	Không có.	Có.
docName	Tên của tài liệu cần xoá.	Chuỗi	Không có.	Có.

Phản hồi

Không có.

getDocument

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

Tham số yêu cầu

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>

Tham số	Mô tả	Loại	Mặc định	Bắt buộc
colName	Tên của bộ sưu tập mà bạn muốn truy xuất tài liệu.	Chuỗi	Không có.	Có.
docName	Tên của tài liệu cần truy xuất.	Chuỗi	Không có.	Có.

Phản hồi

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

truy vấn

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 một bộ lọc.

Tham số queryArray của thao tác 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ảng điều kiện bên trong đại diện cho một phần của điều kiện. Mảng điều kiện luôn có 3 phần tử sau:

Một phần tử bên trái chỉ định trường tập hợp.
Một phần tử ở giữa chỉ định toán tử.
Một phần tử bên phải chỉ định giá trị trường của tập hợp.

Ví dụ sau đây chỉ định 2 mảng điều kiện để lọc dựa trên các trường state và population của tập hợp:

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

Khi chạy, thao tác này được diễn giải là một truy vấn, chẳng hạn như truy vấn sau:

Chọn tất cả các thành phố có state = 'CA' và population < 1000000

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

Tham 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 chỉ mục kết hợp phải hỗ trợ truy vấn có nhiều điều kiện trong Cloud Firestore. Để 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>

Khi chạy, thao tác này được diễn giải là một truy vấn, chẳng hạn như truy vấn sau:

Chọn tất cả các thành phố có state = 'CA' và population < 1000000

Tham số	Mô tả	Loại	Mặc định	Bắt buộc
colName	Tên của bộ sưu tập cần truy vấn.	Chuỗi	Không có.	Có.
queryArray	Một mảng các mảng điều kiện, cùng nhau chỉ định các phần của một bộ lọc. Chỉ định một mảng trống để bỏ qua các điều kiện (không lọc kết quả).	Mảng	Không có.	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 một tài liệu vào một bộ sưu tập Cloud Firestore. Nếu tài liệu đã tồn tại trong bộ sưu tập, thao tác này sẽ ghi đè tài liệu đó.

Tham số yêu cầu

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name",
  "data" : "data-to-copy"
}]]></Input>

Tham số	Mô tả	Loại	Mặc định	Bắt buộc
colName	Tên của bộ sưu tập mà bạn muốn tạo tài liệu.	Chuỗi	Không có.	Có.
docName	Tên của tài liệu mà `data` sẽ được sao chép.	Chuỗi	Không có.	Có.
dữ liệu	Dữ liệu cần sao chép vào `docName`. Đây phải là một đối tượng JSON hợp lệ. Không hỗ trợ mảng.	Đối tượng	Không có.	STT

Phản hồi

Không có.

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

Hãy sử dụng những thông tin 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 phần Thêm và định cấu hình tiện ích.

Thuộc tính mở rộng chung

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ó	Có
`packageName`	Tên của gói tiện ích do Apigee Edge cung cấp.	Không có	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ó	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ác thuộc tính cho gói tiện ích này

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