إضافة Google Cloud Firestore

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

الإصدار: 1.2.0

يمكنك إنشاء البيانات أو قراءتها أو حذفها في قاعدة بيانات Cloud Firestore.

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

  1. إنشاء مشروع Firebase في وحدة تحكّم Firebase حيث يتم تخزين بياناتك

  2. إنشاء مفتاح لحساب الخدمة.

  3. استخدام محتوى ملف JSON للمفتاح الناتج عند إضافة الإضافة وضبطها باستخدام مرجع الإعدادات.

لمحة عن Cloud Firestore

Cloud Firestore تخزّن البيانات في مستندات، ويتم تخزين هذه المستندات في مجموعات. تنشئ Cloud Firestore المجموعات والمستندات ضمنيًا في المرة الأولى التي تضيف فيها بيانات إلى المستند. لست بحاجة إلى إنشاء مجموعات أو مستندات بشكلٍ صريح.

لمزيد من المعلومات عن Cloud Firestore بشكلٍ عام، يُرجى الاطّلاع على مقالة البدء في استخدام Firestore في مستندات Cloud Firestore.

نماذج

توضّح الأمثلة التالية كيفية إعداد دعم إجراءات إضافة Cloud Firestore باستخدام سياسة ExtensionCallout.

إضافة بيانات

تضيف سياسة ExtensionCallout التالية مستندًا باسم freewill@example.com إلى مجموعة users. تحدّد السمة data حقول المستند الجديد وقيمه.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Add-User-Data">
    <DisplayName>Add User Data</DisplayName>
    <Connector>my-cloud-firestore-extension</Connector>
    <Action>setDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "freewill@example.com",
        "data" : {
            "firstName": "Will",
            "lastName": "Witman",
            "address": "270-8243 Tempor St.",
            "city": "Fort Worth",
            "region": "TX",
            "postalCode": "86519",
            "email": "freewill@example.com",
            "username": "freewill444"
        }
    }]]></Input>
</ConnectorCallout>

الحصول على البيانات

في هذا المثال، تستردّ سياسة ExtensionCallout قيمة المستند freewill@example.com من مجموعة users. تم هنا ضبط السمة parsed للعنصر <Output> على false كي تكون النتيجة المعروضة بتنسيق JSON كسلسلة، بدلاً من أن تكون بتنسيق JSON تم تحليله إلى عنصر. لمزيد من المعلومات، يُرجى الاطّلاع على مرجع العنصر <Output>.

<?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>straut-cloud-firestore-extension</Connector>
    <Action>getDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "freewill@example.com"
    }]]></Input>
    <Output parsed="false">firestore.userdata.retrieved</Output>
</ConnectorCallout>

تستخدم سياسة Assign Message التالية قيمة المتغيّر الذي يخزّن استجابة الإضافة لضبط حمولة الاستجابة.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage name="CopyUserDataToResponse">
    <DisplayName>Copy User Data To Response</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{firestore.userdata.retrieved}</Payload>
    </Set>
</AssignMessage>

حذف البيانات

في هذا المثال، تحذف سياسة ExtensionCallout المستند lizzie@example.com من مجموعة users.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Delete-User-Data">
    <DisplayName>Delete User Data</DisplayName>
    <Connector>my-cloud-firestore-extension</Connector>
    <Action>deleteDocument</Action>
    <Input><![CDATA[{
        "colName" : "users",
        "docName" : "lizzie@example.com"
    }]]></Input>
</ConnectorCallout>

طلب البيانات

في هذا المثال، تطلب سياسة ExtensionCallout مجموعة cities. يتم فلترة نتائج طلب البحث حسب الحقلَين state وpopulation. تم هنا ضبط السمة parsed للعنصر <Output> على false كي تكون النتيجة المعروضة بتنسيق JSON كسلسلة، بدلاً من أن تكون بتنسيق JSON تم تحليله إلى عنصر. لمزيد من المعلومات، يُرجى الاطّلاع على مرجع العنصر <Output>.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Query-City-Data">
    <DisplayName>Query City Data</DisplayName>
    <Connector>cloud-firestore-extension</Connector>
    <Action>query</Action>
    <Input><![CDATA[{
        "colName":"cities",
        "queryArray":[
          ["state", "==", "CA"],
          ["population","<",1000000]
        ]
    }]]></Input>
    <Output parsed="false">compound-query-output</Output>
</ConnectorCallout>

تستخدم سياسة Assign Message التالية قيمة المتغيّر الذي يخزّن استجابة الإضافة لضبط حمولة الاستجابة.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage name="CopyQueryResultsToResponse">
    <DisplayName>Copy Query Results To Response</DisplayName>
    <AssignTo type="response" createNew="false"/>
    <Set>
        <Payload contentType="application/json">{firestore.querydata.retrieved}</Payload>
    </Set>
</AssignMessage>

الإجراءات

deleteDocument

يحذف مستندًا واحدًا من مجموعة.

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

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>
المَعلمة الوصف النوع تلقائي مطلوب
colName اسم المجموعة التي تحتوي على المستند المطلوب حذفه سلسلة بلا عُري نعم.
docName اسم المستند المطلوب حذفه سلسلة بلا عُري نعم.

الردّ

بلا عُري

getDocument

يستردّ محتوى مستند واحد.

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

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name"
}]]></Input>
المَعلمة الوصف النوع تلقائي مطلوب
colName اسم المجموعة التي سيتم استرداد المستند منها سلسلة بلا عُري نعم.
docName اسم المستند المطلوب استرداده سلسلة بلا عُري نعم.

الردّ

عنصر يحتوي على محتوى المستند بتنسيق JSON

query

يطلب مجموعة من خلال تحديد الشروط التي تشكّل فلترًا.

تحدّد المَعلمة queryArray لهذا الإجراء مصفوفة من المصفوفات (أو مصفوفة فارغة في حال عدم توفّر شروط فلترة). تحدّد كل مصفوفة داخلية شرطًا من شروط الفلتر. تمثّل المصفوفات الداخلية المتعدّدة شروطًا متعدّدة يتم ربطها بعامل تشغيل AND.

يمثّل كل عنصر في مصفوفة الشروط الداخلية جزءًا من الشرط. تحتوي مصفوفة الشروط دائمًا على العناصر الثلاثة التالية:

  • عنصر على اليمين يحدّد حقل المجموعة
  • عنصر في الوسط يحدّد عامل التشغيل
  • عنصر على اليسار يحدّد قيمة حقل المجموعة

يحدّد المثال التالي مصفوفتَين للشروط للفلترة استنادًا إلى الحقلَين state وpopulation في المجموعة:

<Input><![CDATA[{
  "colName":"cities",
  "queryArray":[
    ["state", "==", "CA"],
    ["population","<",1000000]
  ]
}]]></Input>

في وقت التشغيل، يتم تفسير هذا الإجراء على أنّه طلب بحث مثل ما يلي:

Select all of the cities where state = 'CA' and population < 1000000

يجب أن يكون طلب البحث الذي يتضمّن شروطًا متعدّدة متوافقًا مع Cloud Firestore من خلال فهرس مركّب. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع الفهارس في Cloud Firestore.

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

البنية

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "queryArray" : "queryArray": query-condition-array
}]]></Input>

مثال

في هذا المثال، تحدّد المَعلمة queryArray شرطَين يتم استخدامهما لفلترة مجموعة cities التي تحدّدها المَعلمة colName.

يجب أن يكون طلب البحث الذي يتضمّن شروطًا متعدّدة متوافقًا مع Cloud Firestore من خلال فهرس مركّب. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع الفهارس في Cloud Firestore.

<Input><![CDATA[{
  "colName":"cities",
  "queryArray":[["state", "==", "CA"],["population","<",1000000]]
}]]></Input>

في وقت التشغيل، يتم تفسير هذا الإجراء على أنّه طلب بحث مثل ما يلي:

Select all of the cities where state = 'CA' and population < 1000000

المَعلمة الوصف النوع تلقائي مطلوب
colName اسم المجموعة المطلوب طلبها سلسلة بلا عُري نعم.
queryArray مصفوفة من مصفوفات الشروط التي تحدّد معًا أجزاء الفلتر يمكنك تحديد مصفوفة فارغة لإزالة الشروط (عدم فلترة النتائج). مصفوفة بلا عُري نعم.

الردّ

عنصر يحتوي على محتوى المستند بتنسيق JSON

setDocument

ينسخ مستندًا إلى مجموعة Cloud Firestore. إذا كان المستند موجودًا من قبل في المجموعة، سيتم استبداله.

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

<Input><![CDATA[{
  "colName" : "firestore-collection-name",
  "docName" : "firestore-document-name",
  "data" : "data-to-copy"
}]]></Input>
المَعلمة الوصف النوع تلقائي مطلوب
colName اسم المجموعة التي سيتم إنشاء المستند فيها سلسلة بلا عُري نعم.
docName اسم المستند الذي يجب نسخ data إليه سلسلة بلا عُري نعم.
data البيانات المطلوب نسخها إلى docName يجب أن يكون هذا عنصر JSON صالحًا. لا يمكن استخدام المصفوفات. عنصر بلا عُري لا.

الردّ

بلا عُري

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

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

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

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

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

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

الموقع الوصف تلقائي مطلوب
firestoreDB عنوان URL لقاعدة بيانات Cloud Firestore التي يجب أن تستخدمها هذه الإضافة عند إرسال الطلبات عادةً ما يكون عنوان URL هذا على النحو https://DATABASE_NAME.firebaseio.com. بلا عُري نعم.
credentials عند إدخال هذه البيانات في وحدة تحكّم Apigee Edge، يكون هذا هو محتوى ملف المفتاح الذي أنشأته باستخدام تعليمات Firebase. عند إرسالها من خلال Management API، تكون قيمة بترميز base64 تم إنشاؤها من ملف المفتاح. بلا عُري نعم.