Tiện ích cơ sở dữ liệu Google Cloud Spanner

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

Thực hiện các thao tác chèn, truy vấn và cập nhật trên cơ sở dữ liệu Cloud Spanner.

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 từ một proxy API bằng cách sử dụng chính sách ExtensionCallout, bạn phải:

Tạo một thực thể Cloud Spanner, như mô tả trong phần Tạo và quản lý thực thể, rồi tạo một cơ sở dữ liệu.
Sau khi bạn có phiên bản và cơ sở dữ liệu, hãy cấp quyền truy cập vào cơ sở dữ liệu cho tài khoản dịch vụ Google Cloud đại diện cho tiện ích của bạn. Để biết thêm thông tin về vai trò cần sử dụng, hãy xem phần Các vai trò trong Cloud Spanner. Để biết thêm thông tin về chế độ kiểm soát quyền truy cập vào Cloud Spanner, hãy xem phần Áp dụng vai trò IAM và Kiểm soát quyền truy cập vào Cloud Spanner.
Khi bạn có một tài khoản dịch vụ có quyền truy cập vào cơ sở dữ liệu ở cấp độ mà bạn muốn, hãy sử dụng Google Cloud Console để 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 bạn định cấu hình tiện ích này.
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 Spanner

Cloud Spanner là một dịch vụ cơ sở dữ liệu quan hệ, hữu ích cho dữ liệu quan hệ, có cấu trúc và bán cấu trúc, đòi hỏi khả năng hoạt động cao, tính nhất quán mạnh mẽ, cũng như các hoạt động đọc và ghi giao dịch.

Nếu bạn mới bắt đầu sử dụng Cloud Spanner, thì hướng dẫn bắt đầu nhanh trong tài liệu Cloud Spanner là nơi phù hợp để bắt đầu.

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 Spanner bằng cách sử dụng chính sách ExtensionCallout.

Thêm dữ liệu

Trong ví dụ sau, thao tác insert của tiện ích sẽ thêm một người dùng mới vào bảng người dùng.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Insert-New-User">
    <DisplayName>Insert New User</DisplayName>
    <Connector>spanner-users-products</Connector>
    <Action>insert</Action>
    <Input><![CDATA[{
        "tableName" : "user",
        "rows" : [{
          "username": "jonesy42",
          "firstName": "Floyd",
          "lastName": "Jones",
          "address": "3695 Auctor Street",
          "city": "Gresham",
          "region": "OR",
          "postalCode": "12693",
          "email": "floydster@example.com"
      }]
  }]]></Input>
</ConnectorCallout>

Lấy dữ liệu

Trong ví dụ này, một truy vấn sẽ truy xuất giá trị tên người dùng và email từ bảng user.

Trước tiên, chính sách AssignMessage sẽ chỉ định một biến postal.code.value để sử dụng trong mệnh đề WHERE của truy vấn. Đây là một ví dụ. Chính sách của bạn có thể sẽ đặt giá trị dựa trên các tham số yêu cầu của ứng dụng.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Postal-Code">
    <AssignTo createNew="true" transport="http" type="request"/>
    <AssignVariable>
        <Name>postal.code</Name>
        <Value>86519</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Chính sách ExtensionCallout sau đây thực thi một truy vấn đối với cơ sở dữ liệu, sử dụng nội dung của biến postal.code.value trong mệnh đề WHERE.

<?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>spanner-users-products</Connector>
    <Action>querySQL</Action>
    <Input><![CDATA[{
      "sql" : "SELECT username, email FROM user WHERE postalCode = @postalCode",
      "params" : {
        "postalCode" : "{postal.code.value}"
      }
    }]]></Input>
  <Output>spanner.userdata.retrieved</Output>
</ConnectorCallout>

Sau đó, chính sách AssignMessage sau đây sẽ sử dụng phản hồi của tiện ích (được lưu trữ trong biến spanner.userdata.retrieved) làm phản hồi được trả về cho ứng dụng.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="Get-Query-Response-Data">
    <DisplayName>Get Query Response Data</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{spanner.userdata.retrieved}</Payload>
    </Set>
</AssignMessage>

Trong ví dụ này, dữ liệu phản hồi được trả về dưới dạng JSON, chẳng hạn như sau đây.

{
  "rows": [
    {
      "username": "freewill444",
      "email": "freewill@example.com"
    }
  ]
}

Cập nhật dữ liệu

Trong ví dụ này, phần tử <Input> chứa username (khoá chính của bảng) và một giá trị mới cho cột email.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Update-User-Data">
    <DisplayName>Update User Data</DisplayName>
    <Connector>spanner-users-products</Connector>
    <Action>update</Action>
    <Input><![CDATA[{
        "tableName" : "user",
        "rows": [{
            "username":"Liz456",
            "email":"lizzard@example.com"
        }]
    }]]></Input>
</ConnectorCallout>

Thao tác

insert

Chèn các hàng đã chỉ định vào cơ sở dữ liệu.

Cú pháp

<Action>insert</Action>
<Input><![CDATA[{
  "tableName" : "table-to-insert-into",
  "rows" : "rows-to-insert"
}]]></Input>

Ví dụ:

Trong ví dụ sau, thao tác insert của tiện ích sẽ thêm một người dùng mới vào bảng người dùng. Một hàng sẽ được thêm.

<Action>insert</Action>
<Input><![CDATA[{
    "tableName" : "user",
    "rows" : [{
      "username": "jonesy42",
      "firstName": "Floyd",
      "lastName": "Jones",
      "address": "3695 Auctor Street",
      "city": "Gresham",
      "region": "OR",
      "postalCode": "12693",
      "email": "floydster@example.com"
  }]
}]]></Input>

Tham số yêu cầu

Tham số	Mô tả	Loại	Mặc định	Bắt buộc
tên bảng	Bảng trong cơ sở dữ liệu mà các hàng sẽ được chèn vào.	Chuỗi	Không có.	Có.
hàng	Các hàng cần chèn được biểu thị dưới dạng một mảng trong đối tượng JSON `rows`.	Mảng	Không có.	Có.

Phản hồi

Không có.

querySQL

Truy vấn cơ sở dữ liệu bằng câu lệnh SQL có các tham số được chỉ định. Các tham số được đưa ra trong câu lệnh SQL có tên được thêm @ vào trước; các giá trị tham số được chỉ định trong tham số params của thao tác này.

Để biết thông tin chi tiết về cú pháp truy vấn Cloud Spanner, hãy xem phần Cú pháp truy vấn.

Cú pháp

<Action>querySQL</Action>
<Input><![CDATA[{
  "sql" : "sql-query-statement",
  "params" : {
    "param1" : "columnValue"
  }
}]]></Input>

Ví dụ:

Trong ví dụ này, một truy vấn sẽ truy xuất các giá trị cột username và email từ bảng user. Câu lệnh SQL chỉ định một tham số postalCode được đặt từ biến luồng postal.code.value.

<Action>querySQL</Action>
<Input><![CDATA[{
  "sql" : "SELECT username, email FROM user WHERE postalCode = @postalCode",
  "params" : {
    "postalCode" : "{postal.code.value}"
  }
}]]></Input>

Tham số yêu cầu

Tham số	Mô tả	Loại	Mặc định	Bắt buộc
sql	Truy vấn SQL cần thực thi. Bạn có thể chỉ định các thông số bằng tên thông số được thêm @ vào đầu. Những tên tham số đó phải tương ứng với các khoá trong tham số `params` của thao tác này.	Chuỗi	Không có.	Có.
params	Một đối tượng có khoá và giá trị là tên và giá trị tham số được dùng trong truy vấn SQL. Bạn có thể liệt kê nhiều thông số tại đây.	Đối tượng	Không có.	STT

Phản hồi

Một đối tượng rows chứa một mảng gồm các cặp tên-giá trị cột do truy vấn trả về. Ví dụ:

{
  "rows": [
    {
      "username": "freewill444",
      "email": "freewill@example.com"
    }
  ]
}

cập nhật

Cập nhật các hàng trong cơ sở dữ liệu bằng dữ liệu đã chỉ định.

Cú pháp

<Input><![CDATA[{
  "tableName" : "table-with-rows-to-update",
  "rows" : "rows-to-update"
}]]></Input>

Ví dụ:

Trong ví dụ này, địa chỉ email của người dùng có username là Liz456 được cập nhật bằng một giá trị mới. Một hàng được cập nhật.

<Action>update</Action>
<Input><![CDATA[{
  "tableName" : "user",
  "rows": [{
      "username":"Liz456",
      "email":"lizzard@example.com"
  }]
}]]></Input>

Tham số yêu cầu

Tham số	Mô tả	Loại	Mặc định	Bắt buộc
tên bảng	Bảng trong cơ sở dữ liệu mà các hàng cần được cập nhật.	Chuỗi	Không có.	Có.
hàng	Một mảng dữ liệu hàng cần cập nhật. Mỗi thực thể trong mảng phải chứa giá trị mã nhận dạng duy nhất (chẳng hạn như khoá chính) cho hàng cần cập nhật.	Mảng	Không có.	Có.

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

Chỉ định các giá trị cho các thuộc tính cấu hình sau đây dành riêng cho tiện ích này.

Thuộc tính	Mô tả	Mặc định	Bắt buộc
projectId	Mã nhận dạng của dự án trên Google Cloud chứa cơ sở dữ liệu.	Không có.	Có.
instanceId	Mã nhận dạng của phiên bản Cloud Spanner trong dự án Google Cloud của bạn.	Không có.	Có.
databaseId	Mã nhận dạng của cơ sở dữ liệu Cloud Spanner.	Không có.	Có.
thông tin xác thực	Khi được nhập vào bảng điều khiển Apigee Edge, đây là nội dung của tệp khoá tài khoản dịch vụ. 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á tài khoản dịch vụ.	Không có.	Có.