إضافة قاعدة بيانات Google Cloud Spanner

أنت تطّلع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X.
info

الإصدار 2.0.0

تنفيذ عمليات الإدراج والاستعلام والتحديث في قاعدة بيانات Cloud Spanner

يوفّر هذا المحتوى مرجعًا لضبط هذه الإضافة واستخدامها. قبل استخدام الإضافة من خادم وكيل لواجهة برمجة التطبيقات باستخدام سياسة ExtensionCallout، عليك إجراء ما يلي:

  1. أنشئ مثيلًا على Cloud Spanner، كما هو موضّح في مقالة إنشاء المثيلات وإدارتها، وأنشئ قاعدة بيانات.

  2. بعد الحصول على المثيل وقاعدة البيانات، عليك منح الإذن بالوصول إلى قاعدة البيانات لحساب خدمة GCP الذي يمثّل الإضافة. لمزيد من المعلومات عن الدور الذي تريد استخدامه، راجِع أدوار Cloud Spanner. لمزيد من المعلومات عن التحكّم في الوصول إلى Cloud Spanner، اطّلِع على مقالتَي تطبيق أدوار "إدارة الهوية وإمكانية الوصول" والتحكّم في الوصول إلى Cloud Spanner.

  3. عندما يكون لديك حساب خدمة لديه إذن بمستوى الوصول إلى قاعدة بياناتك الذي تريده، استخدِم وحدة تحكُّم Google Cloud Platform لإنشاء مفتاح لحساب الخدمة. استخدِم محتوى ملف 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>

تنفِّذ سياسة ExtensionCallout التالية طلب بحث في قاعدة البيانات باستخدام محتوى المتغيّر 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>

مَعلمات الطلب

المَعلمة الوصف النوع تلقائي مطلوب
tableName الجدول في قاعدة البيانات الذي يجب إدراج الصفوف فيه سلسلة بلا عُري نعم.
صفوف الصفوف المطلوب إدراجها مُعبّرة عنها كمصفوفة في عنصر rows JSON مصفوفة بلا عُري نعم.

الردّ

بلا عُري

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 لهذا الإجراء. سلسلة بلا عُري نعم.
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>

مَعلمات الطلب

المَعلمة الوصف النوع تلقائي مطلوب
tableName الجدول في قاعدة البيانات الذي يجب تعديل الصفوف فيه سلسلة بلا عُري نعم.
صفوف صفيف لبيانات الصفوف المطلوب تعديلها يجب أن يحتوي كل عنصر في الصفيف على قيمة المعرّف الفريد (مثل المفتاح الأساسي) للصف المطلوب تعديله. مصفوفة بلا عُري نعم.

الردّ

بلا عُري

مرجع الإعدادات

استخدِم ما يلي عند ضبط هذه الإضافة ونشرها لاستخدامها في الخوادم الوكيلة لواجهات برمجة التطبيقات. لمعرفة خطوات ضبط إضافة باستخدام وحدة تحكّم Apigee، اطّلِع على إضافة إضافة وضبطها.

سمات الإضافات الشائعة

السمات التالية متاحة لكل إضافة.

الموقع الوصف تلقائي عنصر مطلوب
name الاسم الذي تُعطِه هذه الإضافة من الإضافات. لا ينطبق متوافق
packageName اسم حزمة الإضافة كما هو مُوضَّح من Apigee Edge. لا ينطبق متوافق
version رقم إصدار حزمة الإضافة التي تجري عملية إعداد الإضافة منها. لا ينطبق متوافق
configuration قيمة الإعداد المتعلقة بالإضافة التي تدرجها الاطّلاع على خصائص حزمة الإضافات هذه لا ينطبق متوافق

سمات حزمة الإضافة هذه

حدِّد قيمًا لسمات الإعدادات التالية الخاصة بهذه الإضافة.

الموقع الوصف تلقائي مطلوب
projectId معرّف مشروع Google Cloud Platform الذي يحتوي على قاعدة البيانات بلا عُري نعم.
instanceId رقم تعريف مثيل Cloud Spanner في مشروعك على Google Cloud Platform بلا عُري نعم.
databaseId رقم تعريف قاعدة بيانات Cloud Spanner بلا عُري نعم.
بيانات الاعتماد عند إدخالها في وحدة تحكّم Apigee Edge، هذه هي محتويات ملف مفتاح حساب الخدمة. عند إرسالها من خلال Management API، تكون قيمة مُشفَّرة بترميز base64 تم إنشاؤها من ملف مفتاح حساب الخدمة. بلا عُري نعم.