مصدر بيانات Cosmos DB للمحلل

مقالة
03/18/2024

cosmosdb-data-source يحل نهج الحل البيانات الخاصة بنوع العنصر وحقل في مخطط GraphQL باستخدام مصدر بيانات Cosmos DB. يجب استيراد المخطط إلى API Management كواجهة برمجة تطبيقات GraphQL.

استخدم النهج لتكوين طلب استعلام واحد أو قراءة طلب أو حذف طلب أو كتابة طلب واستجابة اختيارية من مصدر بيانات Cosmos DB.

إشعار

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

إشعار

تعيين عناصر النهج والعناصر التابعة بالترتيب الوارد في بيان النهج. تعلم كيفية إعداد نُهج APIM أو تعديلها.

نهج السياسة

<cosmosdb-data-source> 
    <!-- Required information that specifies connection to Cosmos DB -->
    <connection-info> 
        <connection-string use-managed-identity="true | false"> 
            AccountEndpoint=...;[AccountKey=...;]
        </connection-string> 
        <database-name>Cosmos DB database name</database-name> 
        <container-name>Name of container in Cosmos DB database</container-name>     
    </connection-info>

    <!-- Settings to query using a SQL statement and optional query parameters -->
    <query-request enable-low-precision-order-by="true | false"> 
        <sql-statement> 
            SQL statement 
        </sql-statement> 
        <parameters> 
            <parameter name="Query parameter name in @ notation"> 
                "Query parameter value or expression"
            </parameter>
            <!-- if there are multiple parameters, then add additional parameter elements --> 
        </parameters> 
        <partition-key data-type="string | number | bool | none | null" template="liquid" > 
            "Container partition key" 
        </partition-key> 
        <paging> 
            <max-item-count template="liquid" > 
                Maximum number of items returned by query
            </max-item-count> 
            <continuation-token template="liquid"> 
                Continuation token for paging 
            </continuation-token> 
        </paging>
    </query-request>
    
    <!-- Settings to read item by item ID and optional partition key --> 
    <read-request> 
        <id template="liquid" >
            "Item ID in container"
        </id> 
        <partition-key data-type="string | number | bool | none | null" template="liquid" > 
            "Container partition key" 
        </partition-key>  
    </read-request> 
    
    <!-- Settings to delete item by ID and optional partition key --> 
    <delete-request consistency-level="bounded-staleness | consistent-prefix | eventual | session | strong" pre-trigger="myPreTrigger" post-trigger="myPostTrigger">
        <etag type="entity tag type" template="liquid" > 
            "System-generated entity tag" 
        </etag> 
        <id template="liquid">
            "Item ID in container"
        </id> 
        <partition-key data-type="string | number | bool | none | null" template="liquid"> 
            "Container partition key" 
        </partition-key> 
    </delete-request> 
    
    <!-- Settings to write item -->
    <write-request type="insert | replace | upsert" consistency-level="bounded-staleness | consistent-prefix | eventual | session | strong" pre-trigger="myPreTrigger" post-trigger="myPostTrigger">
        <id template="liquid">
            "Item ID in container"
        </id>
         <partition-key data-type="string | number | bool | none | null" template="liquid"> 
            "Container partition key"
        </partition-key>      
        <etag type="match | no-match" template="liquid" > 
            "System-generated entity tag" 
        </etag>
        <set-body template="liquid" >...set-body policy configuration...</set-body> 
    </write-request>
    
    <response> 
        <set-body>...set-body policy configuration...</set-body> 
        <publish-event>...publish-event policy configuration...</publish-event>
    </response>
    
</cosmosdb-data-source>

عناصر

Name	‏‏الوصف	مطلوب
معلومات الاتصال	تحديد الاتصال بالحاوية في قاعدة بيانات Cosmos DB.	‏‏نعم‬
طلب الاستعلام	تحديد إعدادات طلب استعلام إلى حاوية Cosmos DB.	تكوين واحد من `query-request`أو `read-requestdelete-request`أو أو`write-request`
طلب القراءة	تحديد إعدادات طلب قراءة إلى حاوية Cosmos DB.	تكوين واحد من `query-request`أو `read-requestdelete-request`أو أو`write-request`
طلب الحذف	تحديد إعدادات طلب حذف إلى حاوية Cosmos DB.	تكوين واحد من `query-request`أو `read-requestdelete-request`أو أو`write-request`
طلب الكتابة	تحديد إعدادات طلب الكتابة إلى حاوية Cosmos DB.	تكوين واحد من `query-request`أو `read-requestdelete-request`أو أو`write-request`
response	يحدد اختياريا النهج التابعة لتكوين استجابة الحل. إذا لم يتم تحديدها، يتم إرجاع الاستجابة من Cosmos DB ك JSON.	لا

عناصر معلومات الاتصال

Name	‏‏الوصف	مطلوب
سلسلة الاتصال	تحديد سلسلة الاتصال لحساب Cosmos DB. إذا تم تكوين هوية مدارة لإدارة واجهة برمجة التطبيقات، فاحذف مفتاح الحساب.	‏‏نعم‬
اسم قاعدة البيانات	السلسلة. اسم قاعدة بيانات Cosmos DB.	‏‏نعم‬
اسم الحاوية	السلسلة. اسم الحاوية في قاعدة بيانات Cosmos DB.	‏‏نعم‬

سمات سلسلة الاتصال

السمة	‏‏الوصف	مطلوبة	افتراضي
استخدام الهوية المدارة	منطقي. يحدد ما إذا كان يجب استخدام الهوية المدارة المعينة من قبل النظام لمثيل API Management للاتصال بحساب Cosmos DB بدلا من مفتاح حساب في سلسلة الاتصال. يجب تكوين الهوية للوصول إلى حاوية Cosmos DB.	لا	`false`

سمات طلب الاستعلام

السمة	‏‏الوصف	مطلوبة	افتراضي
تمكين ترتيب الدقة المنخفضة حسب	منطقي. يحدد ما إذا كان سيتم تمكين خاصية طلب الاستعلام EnableLowPrecisionOrderBy في خدمة Cosmos DB.	لا	‏‫غير متاح

عناصر طلب الاستعلام

Name	‏‏الوصف	مطلوب
عبارة sql	عبارة SQL لطلب الاستعلام.	لا
المعلمات	قائمة معلمات الاستعلام، في العناصر الفرعية للمعلمات ، لطلب الاستعلام.	لا
مفتاح القسم	مفتاح قسم Cosmos DB لتوجيه الاستعلام إلى الموقع في الحاوية.	لا
paging	يحدد الإعدادات لتقسيم نتائج الاستعلام إلى صفحات متعددة.	لا

سمات المعلمة

السمة	‏‏الوصف	مطلوبة	افتراضي
الاسم	السلسلة. اسم المعلمة في الرمز @ .	‏‏نعم‬	غير متوفر

عناصر الترحيل

Name	‏‏الوصف	مطلوب
الحد الأقصى لعدد العناصر	تحديد الحد الأقصى لعدد العناصر التي تم إرجاعها بواسطة الاستعلام. اضبط على -1 إذا كنت لا تريد وضع حد لعدد النتائج لكل تنفيذ استعلام.	‏‏نعم‬
رمز المتابعة المميز	تحديد الرمز المميز للمتابعة لإرفاقه بالاستعلام للحصول على المجموعة التالية من النتائج.	‏‏نعم‬

سمة الحد الأقصى لعدد العناصر

السمة	‏‏الوصف	مطلوبة	افتراضي
القالب	يستخدم لتعيين وضع القولبة ل `max-item-count`. القيمة الوحيدة المدعومة حاليًّا هي: - `liquidmax-item-count`- سوف تستخدم محرك القولبة السائل.	لا	‏‫غير متاح

سمة الرمز المميز للمتابعة

السمة	‏‏الوصف	مطلوبة	افتراضي
القالب	يستخدم لتعيين وضع ال templating للرمز المميز للمتابعة. القيمة الوحيدة المدعومة حاليًّا هي: - `liquid` - الرمز المميز للمتابعة سيستخدم محرك التقزم السائل.	لا	‏‫غير متاح

عناصر طلب القراءة

Name	‏‏الوصف	مطلوب
المعرف	معرف العنصر المراد قراءته في الحاوية.	‏‏نعم‬
مفتاح القسم	مفتاح قسم لموقع العنصر في الحاوية. إذا تم تحديده باستخدام `id`، يمكن قراءة نقطة سريعة (البحث عن المفتاح/القيمة) للعنصر في الحاوية.	لا

حذف سمات الطلب

السمة	‏‏الوصف	مطلوبة	افتراضي
مستوى التناسق	السلسلة. تعيين مستوى تناسق Cosmos DB لطلب الحذف.	لا	‏‫غير متاح
المشغل المسبق	السلسلة. معرف دالة ما قبل التشغيل المسجلة في حاوية Cosmos DB.	لا	‏‫غير متاح
المشغل اللاحق	السلسلة. معرف دالة ما بعد المشغل المسجلة في حاوية Cosmos DB.	لا	‏‫غير متاح

حذف عناصر الطلب

Name	‏‏الوصف	مطلوب
المعرف	معرف العنصر المراد حذفه في الحاوية.	‏‏نعم‬
مفتاح القسم	مفتاح قسم لموقع العنصر في الحاوية.	لا
Etag	علامة الكيان للعنصر في الحاوية، المستخدمة للتحكم في التزامن المتفائل.	لا

سمات طلب الكتابة

السمة	‏‏الوصف	مطلوبة	افتراضي
النوع	نوع طلب الكتابة: `insert`أو `replace`أو .`upsert`	لا	`upsert`
مستوى التناسق	السلسلة. تعيين مستوى تناسق Cosmos DB لطلب الكتابة.	لا	‏‫غير متاح
توجيه الفهرسة	نهج الفهرسة الذي يحدد كيفية فهرسة عناصر الحاوية.	لا	`default`
المشغل المسبق	السلسلة. معرف دالة ما قبل التشغيل المسجلة في حاوية Cosmos DB.	لا	‏‫غير متاح
المشغل اللاحق	السلسلة. معرف دالة ما بعد المشغل المسجلة في حاوية Cosmos DB.	لا	‏‫غير متاح

عناصر طلب الكتابة

Name	‏‏الوصف	مطلوب
المعرف	معرف العنصر في الحاوية.	نعم عندما `type` يكون `replace`.
Etag	علامة الكيان للعنصر في الحاوية، المستخدمة للتحكم في التزامن المتفائل.	لا
تعيين النص الأساسي	تعيين النص الأساسي في طلب الكتابة. إذا لم يتم توفيرها، فستعين حمولة الطلب الوسيطات بتنسيق JSON.	لا

عناصر الاستجابة

Name	‏‏الوصف	مطلوب
تعيين النص الأساسي	تعيين النص الأساسي في استجابة الحلل. إذا لم يتم توفيره ويحتوي JSON الذي تم إرجاعه على حقول مطابقة لأسماء الحقول في مخطط GraphQL، يتم تعيين الحقول تلقائيا.	لا
نشر الحدث	نشر حدث إلى اشتراك واحد أو أكثر محدد في مخطط واجهة برمجة تطبيقات GraphQL.	لا

سمات مفتاح القسم

السمة	‏‏الوصف	مطلوبة	افتراضي
نوع البيانات	نوع بيانات مفتاح القسم: `string`أو `number`أو `nonebool`أو أو .`null`	لا	`string`
القالب	يستخدم لتعيين وضع القولبة لمفتاح القسم. القيمة الوحيدة المدعومة حاليًّا هي: - `liquid` - سيستخدم مفتاح القسم محرك القولبة السائل	لا	‏‫غير متاح

سمة etag

السمة	‏‏الوصف	مطلوبة	افتراضي
النوع	السلسلة. إحدى القيم التالية: - `matchetag`- يجب أن تتطابق القيمة مع علامة الكيان الذي أنشأه النظام للعنصر - `no-matchetag`- القيمة غير مطلوبة لمطابقة علامة الكيان التي أنشأها النظام للعنصر	لا	`match`
القالب	يستخدم لتعيين وضع القولبة ل etag. القيمة الوحيدة المدعومة حاليًّا هي: - `liquid` - سيستخدم etag محرك القولبة السائل	لا	‏‫غير متاح

الاستخدام

نطاقات النهج: محلل GraphQL
البوابات: الكلاسيكية، الإصدار 2

ملاحظات الاستخدام

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

تكوين تكامل الهوية المدارة مع Cosmos DB

يمكنك تكوين هوية مدارة معينة من قبل نظام إدارة واجهة برمجة التطبيقات للوصول إلى حساب Cosmos DB، بدلا من توفير مفتاح حساب في سلسلة الاتصال.

اتبع هذه الخطوات لاستخدام Azure CLI لتكوين الهوية المدارة.

المتطلبات الأساسية

تمكين هوية مدارة معينة بواسطة النظام في مثيل API Management. في المدخل، لاحظ معرف الكائن (الأساسي) للهوية المدارة.
- استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع التشغيل السريع ل Bash في Azure Cloud Shell.
- إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.
  - إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. للحصول على خيارات أخرى لتسجيل دخول، راجع تسجيل الدخول باستخدام Azure CLI.
  - عندما يُطلب منك، قم بتثبيت ملحق Azure CLI عند الاستخدام لأول مرة. لمزيد من المعلومات بشأن الامتدادات، راجع استخدام امتدادات مع Azure CLI.
  - يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.

البرنامج النصي Azure CLI لتكوين الهوية المدارة

# Set variables

# Variable for Azure Cosmos DB account name
cosmosName="<MY-COSMOS-DB-ACCOUNT>"

# Variable for resource group name
resourceGroupName="<MY-RESOURCE-GROUP>"

# Variable for subscription
resourceGroupName="<MY-SUBSCRIPTION-NAME>"

# Set principal variable to the value from Managed identities page of API Management instance in Azure portal
principal="<MY-APIM-MANAGED-ID-PRINCIPAL-ID>"

# Get the scope value of Cosmos DB account
 
scope=$(
    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $cosmosName \
        --subscription $subscriptionName \
        --query id \
        --output tsv
)

# List the built-in Cosmos DB roles
# Currently, the roles aren't visible in the portal

az cosmosdb sql role definition list \
    --resource-group $resourceGroupName \
    --account-name $cosmosName \
    --subscription $subscriptionName \

# Take note of the role you want to assign, such as "Cosmos DB Built-in Data Contributor" in this example

# Assign desired Cosmos DB role to managed identity

az cosmosdb sql role assignment create \
    --resource-group $resourceGroupName \
    --account-name $cosmosName \
    --subscription $subscriptionName \
    --role-definition-name "Cosmos DB Built-in Data Contributor" \
    --principal-id $principal \
    --scope $scope

الأمثلة

طلب استعلام Cosmos DB

يحل المثال التالي استعلام GraphQL باستخدام استعلام SQL إلى حاوية Cosmos DB.

<cosmosdb-data-source>
    <connection-info>
        <connection-string>
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;AccountKey=CONTOSOKEY;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <query-request>
        <sql-statement>SELECT * FROM c </sql-statement>
    </query-request>
</cosmosdb-data-source>

طلب قراءة Cosmos DB

يحل المثال التالي استعلام GraphQL باستخدام طلب قراءة نقطة إلى حاوية Cosmos DB. يستخدم الاتصال بحساب Cosmos DB الهوية المدارة المعينة من قبل النظام لمثيل APIM. يجب تكوين الهوية للوصول إلى حاوية Cosmos DB.

id يتم تمرير و partition-key المستخدمة لطلب القراءة كمعلمات استعلام ويتم الوصول إليها باستخدام context.GraphQL.Arguments["id"] متغير السياق.

<cosmosdb-data-source>
    <connection-info>
        <connection-string use-managed-identity="true">
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <read-request>
        <id>
            @(context.GraphQL.Arguments["id"].ToString())
        </id>
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
    <read-request>
</cosmosdb-data-source>

طلب حذف Cosmos DB

يحل المثال التالي طفرة GraphQL عن طريق طلب حذف إلى حاوية Cosmos DB. id يتم تمرير و partition-key المستخدمة لطلب الحذف كمعلمات استعلام ويتم الوصول إليها باستخدام context.GraphQL.Arguments["id"] متغير السياق.

<cosmosdb-data-source>
    <connection-info>
        <connection-string>
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;AccountKey=CONTOSOKEY;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <delete-request>
        <id>
            @(context.GraphQL.Arguments["id"].ToString())
        </id>
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
        </partition-key>
    </delete-request>
</cosmosdb-data-source>

طلب كتابة Cosmos DB

يحل المثال التالي طفرة GraphQL عن طريق طلب upsert إلى حاوية Cosmos DB. يستخدم الاتصال بحساب Cosmos DB الهوية المدارة المعينة من قبل النظام لمثيل APIM. يجب تكوين الهوية للوصول إلى حاوية Cosmos DB.

partition-key يتم تمرير المستخدم لطلب الكتابة كمعلمة استعلام ويتم الوصول إليه باستخدام context.GraphQL.Arguments["id"] متغير السياق. يحتوي طلب upsert على عملية تشغيل مسبق تسمى "validateInput". يتم تعيين نص الطلب باستخدام قالب سائل.

<cosmosdb-data-source>
    <connection-info>
        <connection-string use-managed-identity="true">
            AccountEndpoint=https://contoso-cosmosdb.
documents.azure.com:443/;
        </connection-string>
        <database-name>myDatabase</database-name>
        <container-name>myContainer</container-name>
    </connection-info>
    <write-request type="upsert" pre-trigger="validateInput">
        <partition-key>
            @(context.GraphQL.Arguments["id"].ToString())
        </partition-key>
        <set-body template="liquid">
            {"id" : "{{body.arguments.id}}" ,
            "firstName" : "{{body.arguments.firstName}}",
            "intField" : {{body.arguments.intField}} ,
            "floatField" : {{body.arguments.floatField}} ,
            "boolField" : {{body.arguments.boolField}}}
        </set-body>
    </write-request>
</cosmosdb-data-source>

إنشاء إدخال معلمة لاستعلام Cosmos DB

توضح الأمثلة التالية طرق إنشاء استعلامات ذات معلمات Cosmos DB باستخدام تعبيرات النهج. اختر أسلوبا استنادا إلى نموذج إدخال المعلمة.

تستند الأمثلة إلى نموذج مخطط GraphQL التالي، وتنشئ الاستعلام المقابل ذي المعلمات Cosmos DB.

مثال على مخطط GraphQL

input personInput {
  id: String!
  firstName: String
}

type Query {
  personsStringParam(stringInput: String): personsConnection
  personsPersonParam(input: personInput): personsConnection
}

مثال استعلام Cosmos DB

{
    "query": "query { 
        personsPersonParam(input: { id: \"3\" } { 
        items { id firstName lastName } 
        } 
    }"
}

تمرير كائن JSON (JObject) من التعبير

مثال على النهج

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param.id</sql-statement>
    <parameters>
        <parameter name="@param">@(context.GraphQL.Arguments["input"])</parameter>
    </parameters>
    </query-request>
[...]

تمرير نوع إدخال .NET (سلسلة، int، عشري، قيمة منطقية) من التعبير

مثال على النهج

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param</sql-statement>
    <parameters>
        <parameter name="@param">@($"start.{context.GraphQL.Arguments["stringInput"]}")</parameter>
    </parameters>
</query-request>
[...]

تمرير قيمة JSON (JValue) من التعبير

مثال على النهج

[...]
<query-request>
    <sql-statement>SELECT * FROM c where c.familyId =@param</sql-statement>
    <parameters>
        <parameter name="@param">@(context.GraphQL.Arguments["stringInput"])</parameter>
    </parameters>
</query-request>
[...]

محللات GraphQL

لمزيد من المعلومات حول العمل مع النُهج، راجع:

البرنامج التعليمي: تحويل واجهة برمجة التطبيقات الخاصة بك وحمايتها
Policy reference لقائمة كاملة من بيانات النُهج وإعداداتها
تعبيرات النهج
تعيين النهج أو تحريرها
إعادة استخدام التكوينات الخاصة بالنهج
مستودع القصاصات البرمجية للنهج
نهج المؤلف باستخدام Microsoft Copilot ل Azure

مشاركة عبر

مصدر بيانات Cosmos DB للمحلل

نهج السياسة

عناصر

عناصر معلومات الاتصال

سمات سلسلة الاتصال

سمات طلب الاستعلام

عناصر طلب الاستعلام

سمات المعلمة

عناصر الترحيل

سمة الحد الأقصى لعدد العناصر

سمة الرمز المميز للمتابعة

عناصر طلب القراءة

حذف سمات الطلب

حذف عناصر الطلب

سمات طلب الكتابة

عناصر طلب الكتابة

عناصر الاستجابة

سمات مفتاح القسم

سمة etag

الاستخدام

ملاحظات الاستخدام

تكوين تكامل الهوية المدارة مع Cosmos DB

المتطلبات الأساسية

البرنامج النصي Azure CLI لتكوين الهوية المدارة

الأمثلة

طلب استعلام Cosmos DB

طلب قراءة Cosmos DB

طلب حذف Cosmos DB

طلب كتابة Cosmos DB

إنشاء إدخال معلمة لاستعلام Cosmos DB

تمرير كائن JSON (JObject) من التعبير

تمرير نوع إدخال .NET (سلسلة، int، عشري، قيمة منطقية) من التعبير

تمرير قيمة JSON (JValue) من التعبير

الموارد الإضافية

مشاركة عبر

مصدر بيانات Cosmos DB للمحلل

نهج السياسة

عناصر

عناصر معلومات الاتصال

سمات سلسلة الاتصال

سمات طلب الاستعلام

عناصر طلب الاستعلام

سمات المعلمة

عناصر الترحيل

سمة الحد الأقصى لعدد العناصر

سمة الرمز المميز للمتابعة

عناصر طلب القراءة

حذف سمات الطلب

حذف عناصر الطلب

سمات طلب الكتابة

عناصر طلب الكتابة

عناصر الاستجابة

سمات مفتاح القسم

سمة etag

الاستخدام

ملاحظات الاستخدام

تكوين تكامل الهوية المدارة مع Cosmos DB

المتطلبات الأساسية

البرنامج النصي Azure CLI لتكوين الهوية المدارة

الأمثلة

طلب استعلام Cosmos DB

طلب قراءة Cosmos DB

طلب حذف Cosmos DB

طلب كتابة Cosmos DB

إنشاء إدخال معلمة لاستعلام Cosmos DB

تمرير كائن JSON (JObject) من التعبير

تمرير نوع إدخال .NET (سلسلة، int، عشري، قيمة منطقية) من التعبير

تمرير قيمة JSON (JValue) من التعبير

النهج ذات الصلة

المحتوى ذو الصلة

الموارد الإضافية