أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى
مستندات Apigee X. info
الإصدار 2.0.2
تنفيذ عمليات الإدراج والاستعلام والتعديل في قاعدة بيانات Cloud Spanner
يوفّر هذا المحتوى مرجعًا لإعداد هذه الإضافة واستخدامها. قبل استخدام الإضافة من خادم وكيل لواجهة برمجة التطبيقات باستخدام سياسة ExtensionCallout، يجب إجراء ما يلي:
أنشئ مثيلاً من Cloud Spanner، كما هو موضّح في إنشاء المثيلات وإدارتها، ثم أنشئ قاعدة بيانات.
بعد إنشاء الجهاز الظاهري وقاعدة البيانات، عليك منح إذن الوصول إلى قاعدة البيانات لحساب خدمة Google Cloud الذي يمثّل الإضافة. لمزيد من المعلومات عن الدور الذي يجب استخدامه، راجِع أدوار Cloud Spanner. لمزيد من المعلومات عن التحكّم في الوصول إلى Cloud Spanner، راجِع تطبيق أدوار "إدارة الهوية وإمكانية الوصول" والتحكّم في الوصول إلى Cloud Spanner.
عندما يكون لديك حساب خدمة لديه إذن بمستوى الوصول الذي تريده إلى قاعدة البيانات، استخدِم Google Cloud Console لإنشاء مفتاح لحساب الخدمة. استخدِم محتوى ملف مفتاح JSON الناتج عند ضبط هذه الإضافة.
استخدِم محتوى ملف مفتاح 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>
مَعلمات الطلب
| المَعلمة | الوصف | النوع | تلقائي | مطلوب |
|---|---|---|---|---|
| اسم الجدول | الجدول في قاعدة البيانات الذي يجب إدراج الصفوف فيه | سلسلة | بلا عُري | نعم. |
| صفوف | الصفوف المطلوب إدراجها معبَّر عنها كمصفوفة في عنصر 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 لهذا الإجراء. |
سلسلة | بلا عُري | نعم. |
| المَعلمات | كائن تكون مفاتيحه وقيمه هي أسماء المَعلمات وقيمها المستخدَمة في طلب 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 تم إنشاؤها من ملف مفتاح حساب الخدمة. | بلا عُري | نعم. |