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

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 2.0.0

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 chính sách ExtensionCallout, bạn phải:

  1. 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.

  2. Sau khi bạn có thực thể 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ụ GCP đại diện cho tiện ích của bạn. Để biết thêm về vai trò cần sử dụng, hãy xem phần Vai trò trong Cloud Spanner. Để biết thêm về tính năng kiểm soát quyền truy cập vào Cloud Spanner, hãy xem bài viết Áp dụng vai trò IAMKiểm soát quyền truy cập vào Cloud Spanner.

  3. 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 Bảng điều khiển GCP để 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.

  4. 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 tệp tham chiếu 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 cao cũng như khả năng đọc và ghi giao dịch.

Nếu bạn mới bắt đầu sử dụng Cloud Spanner, hãy tham khảo hướng dẫn nhanh trong tài liệu về Cloud Spanner.

Mẫu

Các ví dụ sau đây minh hoạ cách định cấu hình tính năng hỗ trợ cho các thao tác mở rộng Cloud Spanner bằ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 các giá trị tên người dùng và email từ bảng user.

Trước tiên, chính sách AssignMessage sẽ gán 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ể đặ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 sẽ thực thi một truy vấn trên 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 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 như sau.

{
  "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. Hệ thống sẽ thêm một hàng.

<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

Thông số Mô tả Loại Mặc định Bắt buộc
tableName Bảng trong cơ sở dữ liệu mà bạn cần chèn các hàng. 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ách sử dụng câu lệnh SQL với các tham số được chỉ định. Các tham số được cung cấp trong câu lệnh SQL có tên bắt đầu bằng @; giá trị tham số được chỉ định trong tham số params của hành động 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, truy vấn sẽ truy xuất các giá trị cột usernameemail từ bảng user. Câu lệnh SQL chỉ định một tham số postalCode được đặt từ biến flow 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

Thông 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 tham số bằng tên tham số có dấu @ ở đầu. Các tên tham số đó phải tương ứng với các khoá trong tham số params của hành động này. Chuỗi Không có. Có.
tham số Một đối tượng có khoá và giá trị là tên và giá trị tham số được sử dụng trong truy vấn SQL. Bạn có thể liệt kê nhiều tham số tại đây. Đối tượng Không có. STT

Phản hồi

Đối tượng rows chứa một mảng 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

Thông số Mô tả Loại Mặc định Bắt buộc
tableName Bảng trong cơ sở dữ liệu cần cập nhật các hàng. 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 nội dung sau đây khi bạn định cấu hình và triển khai tiện ích này để sử dụng trong proxy API. Để biết các bước định cấu hình 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.

Các thuộc tính mở rộng 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ó

Thuộc tính cho gói tiện ích này

Chỉ định 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ã của dự án GCP chứa cơ sở dữ liệu. Không có. Có.
instanceId Mã của thực thể Cloud Spanner trong dự án GCP. Không có. Có.
databaseId Mã của cơ sở dữ liệu Cloud Spanner. Không có. Có.
thông tin xác thực Khi 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 qua API quản lý, đây là một giá trị được mã hoá base64 được tạo từ tệp khoá tài khoản dịch vụ. Không có. Có.