إضافة Google Cloud Firestore

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

الإصدار: 2.0.2

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

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

أنشئ مشروع Firebase في وحدة تحكّم Firebase حيث يتم تخزين بياناتك.
إنشاء مفتاح لحساب الخدمة
استخدِم محتوى ملف مفتاح 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>

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

<?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 policy بيانات من مجموعة 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>

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

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

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

اختَر جميع المدن التي تكون فيها الولاية = "CA" والسكان < 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>

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

اختَر جميع المدن التي تكون فيها الولاية = "CA" والسكان < 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` إليه.	سلسلة	بلا عُري	نعم.
البيانات	البيانات التي سيتم نسخها إلى `docName` يجب أن يكون هذا الكائن كائن JSON صالحًا. لا يمكن استخدام المصفوفات.	عنصر	بلا عُري	لا.

الردّ

بلا عُري

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

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

خصائص الإضافة الشائعة

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

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

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

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