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

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

الإصدار 1.4.2

يمكنك إجراء عمليات الإدراج والاستعلام والتعديل على قاعدة بيانات Cloud Spanner.

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

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

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

  3. عند توفّر حساب خدمة لديه إذن الوصول إلى مستوى الوصول المطلوب إلى قاعدة البيانات، استخدِم وحدة تحكّم GCP لإنشاء مفتاح لحساب الخدمة. استخدِم محتويات ملف 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 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 لهذا الإجراء. سلسلة بلا عُري نعم.
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 الجدول في قاعدة البيانات المطلوب تعديل الصفوف فيه سلسلة بلا عُري نعم.
rows مصفوفة من بيانات الصفوف المطلوب تعديلها يجب أن يحتوي كل كيان في المصفوفة على رقم التعريف الفريد (مثل المفتاح الأساسي) للصف المطلوب تعديله. مصفوفة بلا عُري نعم.

الردّ

بلا عُري

مرجع الإعداد

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

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

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

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

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

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

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