إضافة Google Cloud Firestore

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

الإصدار: 2.0.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>

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

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

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

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

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

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

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

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

الردّ

بلا عُري

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

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

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

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

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

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

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