Google Cloud Spanner Database Extension

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید.
اطلاعات

نسخه ۲.۰.۱

عملیات درج، پُرسمان، و به‌روزرسانی را در پایگاه داده Cloud Spanner انجام دهید.

این محتوا مرجعی برای پیکربندی و استفاده از این افزونه ارائه می‌دهد. قبل‌از استفاده از افزونه از یک پراکسی API بااستفاده از خط‌مشی ExtensionCallout، باید:

  1. همان‌طور که در ایجاد و مدیریت نمونه‌ها توضیح داده شده است، نمونه Cloud Spanner ایجاد کنید و پایگاه داده‌ای بسازید.

  2. پس‌از اینکه نمونه و پایگاه داده را داشتید، به حساب سرویس Google Cloud که نماینده افزونه شما است اجازه دسترسی به پایگاه داده‌تان را بدهید. برای اطلاعات بیشتر درباره نقش مورد استفاده، به نقش‌های Cloud Spanner مراجعه کنید. برای اطلاعات بیشتر درباره کنترل دسترسی Cloud Spanner، اعمال نقش‌های IAM و کنترل دسترسی برای Cloud Spanner را ببینید.

  3. وقتی حساب سرویسی دارید که اجازه دسترسی به سطح موردنظرتان در پایگاه داده را دارد، از Google Cloud Console برای تولید کلید حساب سرویس استفاده کنید. هنگام پیکربندی این افزونه، از محتوای فایل JSON کلید حاصل استفاده کنید.

  4. از محتوای فایل JSON کلید حاصل هنگام افزودن و پیکربندی افزونه بااستفاده از مرجع پیکربندی استفاده کنید.

درباره Cloud Spanner

Cloud Spanner سرویس پایگاه داده رابطه‌ای است که برای داده‌های رابطه‌ای، ساختاریافته، و نیمه‌ساختاریافته که به دردسترس بودن بالا، سازگاری قوی، و خواندن و نوشتن تراکنشی نیاز دارند مفید است.

اگر به‌تازگی کار با Cloud Spanner را شروع کرده‌اید، شروع سریع در اسناد Cloud Spanner مکان خوبی برای شروع است.

نمونه‌ها

مثال‌های زیر نشان می‌دهد که چگونه پشتیبانی از کنش‌های افزونه Cloud Spanner را بااستفاده از خط‌مشی ExtensionCallout پیکربندی کنید.

افزودن داده

در مثال زیر، کنش insert افزونه کاربر جدیدی را به جدول کاربر اضافه می‌کند.

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

دریافت داده

در این مثال، پُرسمان مقادیر نام کاربری و ایمیل را از جدول user بازیابی می‌کند.

ابتدا، یک خط‌مشی AssignMessage متغیر postal.code.value را برای استفاده در بند WHERE یک پُرسمان اختصاص می‌دهد. این یک مثال است. خط‌مشی شما احتمالاً مقدار را براساس پارامترهای درخواست کارخواه تنظیم می‌کند.

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

خط‌مشی «افزونه‌پیام‌واره» زیر بااستفاده از محتوای متغیر postal.code.value در بند 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>

سپس خط‌مشی AssignMessage زیر از پاسخ افزونه، ذخیره‌شده در متغیر spanner.userdata.retrieved، به‌عنوان پاسخ برگشتی به مشتری استفاده می‌کند.

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

در این مثال، داده‌های پاسخ به‌صورت JSON مثل موارد زیر برگردانده می‌شود.

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

به‌روزرسانی داده‌ها

در این مثال، عنصر <Input> حاوی username -- کلید اصلی جدول -- و مقدار جدیدی برای ستون 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>

کنش‌ها

insert

ردیف‌های مشخص‌شده را در پایگاه داده درج می‌کند.

نحو

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

مثال

در مثال زیر، کنش insert افزونه کاربر جدیدی را به جدول کاربر اضافه می‌کند. یک ردیف اضافه شد.

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

پارامترهای درخواست

پارامتر شرح نوع پیش‌فرض الزامی
نام جدول جدول موجود در پایگاه داده که ردیف‌ها باید در آن درج شود. رشته هیچ‌کدام. بله.
ردیف‌ها ردیف‌هایی که باید درج شود به‌صورت آرایه در شیء JSON rows بیان می‌شود. آرایه هیچ‌کدام. بله.

پاسخ

هیچ‌کدام.

querySQL

بااستفاده از دستور SQL با پارامترهای مشخص‌شده، پایگاه داده را پُرسمان می‌کند. پارامترها در عبارت SQL با نام‌های پیش‌رونده @ ارائه می‌شوند؛ مقادیر پارامتر در پارامتر params این کنش مشخص می‌شوند.

برای جزئیات درباره نحو پُرسمان Cloud Spanner، به نحو پُرسمان مراجعه کنید.

نحو

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

مثال

در این مثال، پُرسمانی مقادیر ستون username و email را از جدول user بازیابی می‌کند. عبارت SQL پارامتر postalCode را مشخص می‌کند که از متغیر جاری postal.code.value تنظیم شده است.

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

پارامترهای درخواست

پارامتر شرح نوع پیش‌فرض الزامی
sql پُرسمان SQL برای اجرا. می‌توانید پارامترها را با نام‌های پارامتر پیش‌رونده @ مشخص کنید. این نام‌های پارامتر باید با کلیدهای پارامتر params این کنش مطابقت داشته باشد. رشته هیچ‌کدام. بله.
پارامترها شیئی که کلیدها و مقادیر آن نام‌ها و مقادیر پارامترهای استفاده‌شده در پُرسمان SQL است. می‌توانید چندین پارامتر را در اینجا فهرست کنید. شیء هیچ‌کدام. شماره.

پاسخ

شیء rows حاوی آرایه‌ای از جفت‌های نام-مقدار ستون که توسط پُرسمان برگردانده شده است. برای مثال:

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

به‌روز کردن

ردیف‌های پایگاه داده را با داده‌های مشخص‌شده به‌روز می‌کند.

نحو

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

مثال

در این مثال، نشانی ایمیل کاربری که username او Liz456 است با مقدار جدیدی به‌روزرسانی می‌شود. یک ردیف به‌روز شد.

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

پارامترهای درخواست

پارامتر شرح نوع پیش‌فرض الزامی
نام جدول جدول در پایگاه داده که ردیف‌ها باید در آن به‌روز شوند. رشته هیچ‌کدام. بله.
ردیف‌ها آرایه‌ای از داده‌های ردیف برای به‌روزرسانی. هر نهاد در آرایه باید مقدار شناسه یکتا (مثل کلید اصلی) برای ردیف به‌روزرسانی را داشته باشد. آرایه هیچ‌کدام. بله.

پاسخ

هیچ‌کدام.

مرجع پیکربندی

هنگام پیکربندی و استقرار این افزونه برای استفاده در پراکسی‌های API، از موارد زیر استفاده کنید. برای مراحل پیکربندی افزونه بااستفاده از کنسول Apigee، به افزودن و پیکربندی افزونه مراجعه کنید.

دارایی‌های افزونه مشترک

ویژگی های زیر برای هر افزونه وجود دارد.

ویژگی شرح پیش فرض ضروری
name نامی که به این پیکربندی افزونه می‌دهید. هیچ یک آره
packageName نام بسته افزودنی همانطور که توسط Apigee Edge داده شده است. هیچ یک آره
version شماره نسخه بسته برنامه افزودنی که از آن یک برنامه افزودنی را پیکربندی می کنید. هیچ یک آره
configuration مقدار پیکربندی مخصوص افزونه ای که اضافه می کنید. به ویژگی های این بسته برنامه افزودنی مراجعه کنید هیچ یک آره

دارایی‌های این بسته افزونه

مقادیر مشخصه‌های پیکربندی زیر را که مختص این افزونه است مشخص کنید.

دارایی شرح پیش‌فرض الزامی
projectId شناسه پروژه Google Cloud که حاوی پایگاه داده است. هیچ‌کدام. بله.
instanceId شناسه نمونه Cloud Spanner در پروژه Google Cloud شما. هیچ‌کدام. بله.
databaseId شناسه پایگاه داده Cloud Spanner. هیچ‌کدام. بله.
اطلاعات اعتباری وقتی در کنسول Apigee Edge وارد می‌شود، این محتوای فایل کلید حساب سرویس شما است. وقتی بااستفاده از «میانای برنامه‌سازی کاربردی مدیریت» ارسال می‌شود، مقدار رمزگذاری‌شده با base64 است که از فایل کلید حساب سرویس تولید می‌شود. هیچ‌کدام. بله.