Ekstensi Database Google Cloud Spanner

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X.
info

Versi 1.4.1

Melakukan operasi penyisipan, kueri, dan pembaruan pada database Cloud Spanner.

Konten ini menyediakan referensi untuk mengonfigurasi dan menggunakan ekstensi ini. Sebelum menggunakan ekstensi dari proxy API menggunakan kebijakan ExtensionCallout, Anda harus:

  1. Buat instance Cloud Spanner seperti yang dijelaskan dalam Membuat dan Mengelola Instance, lalu membuat database.

  2. Setelah memiliki instance dan database, berikan izin untuk mengakses database Anda ke akun layanan GCP yang mewakili ekstensi Anda. Untuk mengetahui informasi selengkapnya tentang peran yang akan digunakan, lihat Peran Cloud Spanner. Untuk mengetahui informasi selengkapnya tentang kontrol akses Cloud Spanner, lihat Menerapkan Peran IAM dan Kontrol Akses untuk Cloud Spanner.

  3. Jika Anda memiliki akun layanan yang memiliki izin untuk level akses ke database yang diinginkan, gunakan GCP Console untuk membuat kunci untuk akun layanan. Gunakan konten file JSON kunci yang dihasilkan saat mengonfigurasi ekstensi ini.

  4. Gunakan konten file JSON kunci yang dihasilkan saat menambahkan dan mengonfigurasi ekstensi menggunakan referensi konfigurasi.

Tentang Cloud Spanner

Cloud Spanner adalah layanan database relasional yang berguna untuk data relasional, terstruktur, dan semi-terstruktur yang memerlukan ketersediaan tinggi, konsistensi kuat, dan pembacaan dan penulisan transaksional.

Jika Anda baru mulai menggunakan Cloud Spanner, panduan memulai dalam dokumentasi Cloud Spanner merupakan tempat yang tepat untuk memulai.

Contoh

Contoh berikut menggambarkan cara mengonfigurasi dukungan untuk tindakan ekstensi Cloud Spanner menggunakan kebijakan ExtensionInfo.

Tambahkan data

Pada contoh berikut, tindakan insert ekstensi menambahkan pengguna baru ke tabel pengguna.

<?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>

Mendapatkan data

Dalam contoh ini, kueri mengambil nama pengguna dan nilai email dari tabel user.

Pertama, kebijakanAssignMessage menetapkan variabel postal.code.value untuk digunakan dalam klausa WHERE kueri. Ini adalah contohnya. Kebijakan Anda mungkin akan menetapkan nilai berdasarkan parameter permintaan klien.

<?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>

Kebijakan ExtensionCallout berikut mengeksekusi kueri terhadap database, menggunakan konten variabel postal.code.value dalam klausa 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>

Kemudian, kebijakanAssignMessage berikut menggunakan respons ekstensi, yang disimpan dalam variabel spanner.userdata.retrieved, sebagai respons yang ditampilkan ke klien.

<?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>

Dalam contoh ini, data respons ditampilkan sebagai JSON seperti berikut.

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

Memperbarui data

Dalam contoh ini, elemen <Input> berisi username -- kunci utama tabel -- dan nilai baru untuk kolom 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>

Tindakan

insert

Menyisipkan baris yang ditentukan ke database.

Sintaksis

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

Contoh

Pada contoh berikut, tindakan insert ekstensi menambahkan pengguna baru ke tabel pengguna. Satu baris ditambahkan.

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

Parameter permintaan

Parameter Deskripsi Jenis Default Wajib
tableName Tabel dalam database tempat baris harus disisipkan. String Tidak ada. Ya.
baris Baris yang akan disisipkan dinyatakan sebagai array dalam objek JSON rows. Array Tidak ada. Ya.

Respons

Tidak ada.

querySQL

Mengkueri database menggunakan pernyataan SQL dengan parameter yang telah ditentukan. Parameter diberikan dalam pernyataan SQL dengan nama @diawali; nilai parameter ditentukan dalam parameter params tindakan ini.

Untuk mengetahui detail tentang sintaksis kueri Cloud Spanner, lihat Sintaksis Kueri.

Sintaksis

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

Contoh

Dalam contoh ini, kueri mengambil nilai kolom username dan email dari tabel user. Pernyataan SQL menentukan parameter postalCode yang ditetapkan dari variabel flow postal.code.value.

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

Parameter permintaan

Parameter Deskripsi Jenis Default Wajib
sql Kueri SQL yang akan dieksekusi. Anda dapat menentukan parameter dengan nama parameter @-preended. Nama parameter tersebut harus sesuai dengan kunci dalam parameter params tindakan ini. String Tidak ada. Ya.
params Objek yang kunci dan nilainya adalah nama dan nilai parameter yang digunakan dalam kueri SQL. Anda dapat mencantumkan beberapa parameter di sini. Object Tidak ada. Tidak.

Respons

Objek rows yang berisi array pasangan nama-nilai kolom yang ditampilkan oleh kueri. Contoh:

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

ubah

Memperbarui baris dalam database dengan data yang ditentukan.

Sintaksis

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

Contoh

Dalam contoh ini, alamat email untuk pengguna yang username-nya adalah Liz456 diperbarui dengan nilai baru. Satu baris diperbarui.

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

Parameter permintaan

Parameter Deskripsi Jenis Default Wajib
tableName Tabel dalam database tempat baris akan diperbarui. String Tidak ada. Ya.
baris Array data baris yang akan diperbarui. Setiap entitas dalam array harus berisi nilai ID unik (seperti kunci utama) untuk baris yang akan diperbarui. Array Tidak ada. Ya.

Respons

Tidak ada.

Referensi Konfigurasi

Gunakan hal berikut saat Anda mengonfigurasi dan men-deploy ekstensi ini untuk digunakan di proxy API. Untuk langkah-langkah mengonfigurasi ekstensi menggunakan konsol Apigee, lihat Menambahkan dan mengonfigurasi ekstensi.

Properti ekstensi umum

Properti berikut ada untuk setiap ekstensi.

Properti Deskripsi Default Wajib
name Nama yang Anda berikan pada konfigurasi ekstensi ini. Tidak ada Ya
packageName Nama paket ekstensi seperti yang diberikan oleh Apigee Edge. Tidak ada Ya
version Nomor versi untuk paket ekstensi tempat Anda mengonfigurasi ekstensi. Tidak ada Ya
configuration Nilai konfigurasi khusus untuk ekstensi yang Anda tambahkan. Lihat Properti untuk paket ekstensi ini Tidak ada Ya

Properti untuk paket ekstensi ini

Tentukan nilai untuk properti konfigurasi berikut yang khusus untuk ekstensi ini.

Properti Deskripsi Default Wajib
projectId ID project GCP yang berisi database. Tidak ada. Ya.
instanceId ID instance Cloud Spanner di project GCP Anda. Tidak ada. Ya.
databaseId ID database Cloud Spanner. Tidak ada. Ya.
kredensial Saat dimasukkan di konsol Apigee Edge, ini adalah isi file kunci akun layanan Anda. Saat dikirim melalui API pengelolaan, nilai tersebut adalah nilai berenkode base64 yang dihasilkan dari file kunci akun layanan. Tidak ada. Ya.