استخدام الهويات المدارة المعينة من قبل النظام للوصول إلى بيانات Azure Cosmos DB

ينطبق على: NoSQL

في هذه المقالة، ستقوم بإعداد حل قوي وغير محدد لدوران المفاتيح للوصول إلى مفاتيح Azure Cosmos DB باستخدام الهويات المُدارة والتحكم في الوصول المستند إلى دور مستوى البيانات. يستخدم المثال في هذه المقالة وظائف Azure، ولكن يمكنك استخدام أي خدمة تدعم الهويات المدارة.

ستتعلم كيفية إنشاء تطبيق وظيفي يمكنه الوصول إلى بيانات Azure Cosmos DB دون الحاجة إلى نسخ أي من مفاتيح Azure Cosmos DB. سيتم تشغيل تطبيق الوظيفة عند إجراء طلب HTTP ومن ثم سرد جميع قواعد البيانات الموجودة.

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

  • حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.

  • واجهة برمجة تطبيقات Azure Cosmos DB موجودة لحساب NoSQL. إنشاء واجهة برمجة تطبيقات Azure Cosmos DB لحساب NoSQL

  • تطبيق Azure Functions موجود. إنشاء دالتك الأولى في مدخل Microsoft Azure

  • أدوات Azure Functions الأساسية

  • لتنفيذ الخطوات الواردة في هذه المقالة، ثبّت Azure CLI وسجّل الدخول إلى Azure.

    التحقق من المتطلبات الأساسية

    1. في محطة طرفية أو نافذة أوامر، قم بتخزين أسماء تطبيق Azure Functions الخاص بك، وحساب Azure Cosmos DB ومجموعة الموارد كمتغيرات shell المسماة functionName وcosmosName وresourceGroupName.

      # Variable for function app name
      functionName="msdocs-function-app"
      
      # Variable for Azure Cosmos DB account name
      cosmosName="msdocs-cosmos-app"
      
      # Variable for resource group name
      resourceGroupName="msdocs-cosmos-functions-dotnet-identity"
      

      إشعار

      يعاد استخدام هذه المتغيرات في خطوات لاحقة. يفترض هذا المثال أن اسم حساب Azure Cosmos DB الخاص بك هو msdocs-cosmos-app، واسم تطبيق الوظيفة هو msdocs-function-app واسم مجموعة الموارد هو msdocs-cosmos-functions-dotnet-identity.

    2. اعرض خصائص تطبيق الوظيفة باستخدام الأمر az functionapp show.

      az functionapp show \
          --resource-group $resourceGroupName \
          --name $functionName
      
    3. اعرض خصائص الهوية المُدارة التي عيّنها النظام لتطبيق وظيفتك باستخدام az webapp identity show.

      az webapp identity show \
          --resource-group $resourceGroupName \
          --name $functionName
      
    4. عرض خصائص حساب Azure Cosmos DB باستخدام az cosmosdb show.

      az cosmosdb show \
          --resource-group $resourceGroupName \
          --name $cosmosName
      

إنشاء واجهة برمجة تطبيقات Azure Cosmos DB لقواعد بيانات NoSQL

في هذه الخطوة، يمكنك إنشاء قاعدتي بيانات.

  1. في محطة طرفية أو نافذة أوامر، قم بإنشاء قاعدة بيانات products جديدة باستخدام az cosmosdb sql database create.

    az cosmosdb sql database create \
        --resource-group $resourceGroupName \
        --name products \
        --account-name $cosmosName
    
  2. قم بإنشاء قاعدة بيانات customers جديدة.

    az cosmosdb sql database create \
        --resource-group $resourceGroupName \
        --name customers \
        --account-name $cosmosName
    

الحصول على واجهة برمجة تطبيقات Azure Cosmos DB لنقطة نهاية NoSQL

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

  1. استخدم az cosmosdb show مع تعيين معلمة الاستعلام على documentEndpoint. سجل النتيجة. ستستخدم هذه القيمة في خطوة لاحقة.

    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $cosmosName \
        --query documentEndpoint
    
    cosmosEndpoint=$(
        az cosmosdb show \
            --resource-group $resourceGroupName \
            --name $cosmosName \
            --query documentEndpoint \
            --output tsv
    )
    
    echo $cosmosEndpoint
    

    إشعار

    يعاد استخدام هذا المتغير في خطوة لاحقة.

منح حق الوصول إلى حساب Azure Cosmos DB الخاص بك

في هذه الخطوة، يمكنك تعيين دور للهوية المدارة المعينة من قبل النظام لتطبيق الوظائف. يحتوي Azure Cosmos DB على العديد من الأدوار المضمنة التي يمكنك تعيينها إلى الهوية المدارة للوصول إلى مستوى التحكم. للوصول إلى مستوى البيانات، يمكنك إنشاء دور مخصص جديد مع الوصول إلى بيانات التعريف للقراءة.

تلميح

لمزيد من المعلومات حول أهمية أقل امتياز للوصول، راجع مقالة تعرض أقل للحسابات المميزة.

  1. استخدم az cosmosdb show مع تعيين معلمة الاستعلام على id. قم بتخزين النتيجة في متغير shell يسمى scope.

    scope=$(
        az cosmosdb show \
            --resource-group $resourceGroupName \
            --name $cosmosName \
            --query id \
            --output tsv
    )
    
    echo $scope
    

    إشعار

    يعاد استخدام هذا المتغير في خطوة لاحقة.

  2. استخدم az webapp identity show مع تعيين معلمة الاستعلام على principalId. قم بتخزين النتيجة في متغير shell يسمى principal.

    principal=$(
        az webapp identity show \
            --resource-group $resourceGroupName \
            --name $functionName \
            --query principalId \
            --output tsv
    )
    
    echo $principal
    
  3. إنشاء ملف JSON جديد مع تكوين الدور المخصص الجديد.

    {
        "RoleName": "Read Azure Cosmos DB Metadata",
        "Type": "CustomRole",
        "AssignableScopes": ["/"],
        "Permissions": [{
            "DataActions": [
                "Microsoft.DocumentDB/databaseAccounts/readMetadata"
            ]
        }]
    }
    

    تلميح

    يمكنك إنشاء ملف في Azure Cloud Shell باستخدام إما touch <filename> أو المحرر المضمن (code .). لمزيد من المعلومات، راجع محرر Azure Cloud Shell

  4. استخدم az cosmosdb sql role definition create لإنشاء تعريف دور جديد يسمى Read Azure Cosmos DB Metadata باستخدام عنصر JSON المخصص.

    az cosmosdb sql role definition create \
        --resource-group $resourceGroupName \
        --account-name $cosmosName \
        --body @definition.json
    

    إشعار

    في هذا المثال، يتم تعريف الدور في ملف يسمى definition.json.

  5. استخدم az role assignment create لتعيين الدور Read Azure Cosmos DB Metadata للهوية المدارة من قبل النظام.

    az cosmosdb sql role assignment create \
        --resource-group $resourceGroupName \
        --account-name $cosmosName \
        --role-definition-name "Read Azure Cosmos DB Metadata" \
        --principal-id $principal \
        --scope $scope
    

الوصول برمجيا إلى مفاتيح Azure Cosmos DB

لدينا الآن تطبيق وظائف له هوية مدارة معينة من قبل النظام مع الدور المخصص. سيقوم تطبيق الوظائف التالي بالاستعلام عن حساب Azure Cosmos DB للحصول على قائمة بقواعد البيانات.

  1. قم بإنشاء مشروع وظيفة محلي باستخدام المعلمة --dotnet في مجلد باسم csmsfunc. تغيير دليل shell الخاص بك

    func init csmsfunc --dotnet
    
    cd csmsfunc
    
  2. أنشئ وظيفة جديدة مع تعيين معلمة القالب على httptrigger وتعيين الاسم على readdatabases.

    func new --template httptrigger --name readdatabases
    
  3. أضف الحزمة Azure.Identity وMicrosoft.Azure.Cosmos NuGet إلى مشروع .NET. ابنِ المشروع باستخدام dotnet build.

    dotnet add package Azure.Identity
    
    dotnet add package Microsoft.Azure.Cosmos
    
    dotnet build
    
  4. افتح التعليمة البرمجية للوظيفة في بيئة مطور متكاملة (IDE).

    تلميح

    إذا كنت تستخدم Azure CLI محلياً أو في Azure Cloud Shell، يمكنك فتح Visual Studio Code.

    code .
    
  5. استبدل التعليمة البرمجية الموجودة في ملف readdatabases.cs بهذا التطبيق لوظيفة العينة. احفظ الملف المحدث.

    using System;
    using System.Collections.Generic;
    using System.Threading.Tasks;
    using Azure.Identity;
    using Microsoft.AspNetCore.Mvc;
    using Microsoft.Azure.Cosmos;
    using Microsoft.Azure.WebJobs;
    using Microsoft.Azure.WebJobs.Extensions.Http;
    using Microsoft.AspNetCore.Http;
    using Microsoft.Extensions.Logging;
    
    namespace csmsfunc
    {
        public static class readdatabases
        {
            [FunctionName("readdatabases")]
            public static async Task<IActionResult> Run(
                [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req,
                ILogger log)
            {
                log.LogTrace("Start function");
    
                CosmosClient client = new CosmosClient(
                    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT", EnvironmentVariableTarget.Process),
                    new DefaultAzureCredential()
                );
    
                using FeedIterator<DatabaseProperties> iterator = client.GetDatabaseQueryIterator<DatabaseProperties>();
    
                List<(string name, string uri)> databases = new();
                while(iterator.HasMoreResults)
                {
                    foreach(DatabaseProperties database in await iterator.ReadNextAsync())
                    {
                        log.LogTrace($"[Database Found]\t{database.Id}");
                        databases.Add((database.Id, database.SelfLink));
                    }
                }
    
                return new OkObjectResult(databases);
            }
        }
    }
    

(اختياري) تشغيل الدالة محليا

في بيئة محلية DefaultAzureCredential ، تستخدم الفئة بيانات اعتماد محلية مختلفة لتحديد الهوية الحالية. أثناء كون التشغيل محلياً ليس مطلوباً للكيفية، يمكنك التطوير محلياً باستخدام هويتك الخاصة أو كيان الخدمة.

  1. احصل على المعرف الأساسي لحسابك المحلي باستخدام az ad signed-in-user show.

    az ad signed-in-user show --query "id"
    
  2. قم بتعيين الوصول إلى التحكم في الوصول المستند إلى دور حسابك المحلي إلى حساب Azure Cosmos DB باستخدام az cosmosdb sql role assignment create الأمر . استخدم دور "Cosmos DB Data Contributor" المضمن بمعرف 00000000-0000-0000-0000-000000000002.

    az cosmosdb sql role assignment create \
        --resource-group $resourceGroupName \
        --account-name $cosmosName \
        --role-definition-id "00000000-0000-0000-0000-000000000002" \
        --principal-id "<your-principal-id>" \
        --scope "/"
    
  3. في ملف local.settings.json، أضف إعداداً جديداً باسم COSMOS_ENDPOINT في عنصر Values. يجب أن تكون قيمة الإعداد هي نقطة نهاية المستند التي سجلتها مسبقاً في إرشاد الكيفية.

    ...
    "Values": {
        ...
        "COSMOS_ENDPOINT": "https://msdocs-cosmos-app.documents.azure.com:443/",
        ...
    }
    ...
    

    إشعار

    تم تقصير عنصر JSON للإيجاز. يتضمن عنصر JSON أيضاً عينة للقيمة التي تفترض أن اسم حسابك هو msdocs-cosmos-app.

  4. تشغيل تطبيق الوظيفة

    func start
    

التوزيع إلى Azure

بمجرد النشر، DefaultAzureCredential تستخدم الفئة بيانات الاعتماد من البيئة أو هوية مدارة. بالنسبة لهذا الإرشاد، سيتم استخدام الهوية المُدارة التي عيّنها النظام كبيانات اعتماد للدالة الإنشائية CosmosClient.

  1. قم بتعيين الإعداد COSMOS_ENDPOINT على تطبيق الوظائف الذي تم توزيعه بالفعل في Azure.

    az functionapp config appsettings set \
        --resource-group $resourceGroupName \
        --name $functionName \
        --settings "COSMOS_ENDPOINT=$cosmosEndpoint"
    
  2. قم بتوزيع تطبيق وظيفتك على Azure عن طريق إعادة استخدام متغير shell functionName:

    func azure functionapp publish $functionName
    
  3. اختبر وظيفتك في مدخل Microsoft Azure.