مصادقة الطلبات إلى خدمات Azure الذكاء الاصطناعي

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

• المصادقة باستخدام مفتاح مورد خدمة واحدة أو متعدد الخدمات
• المصادقة باستخدام رمز مميز
• المصادقة باستخدام معرف Microsoft Entra

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

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

يمكنك الحصول على مفتاح المورد الخاص بك من مدخل Microsoft Azure بعد إنشاء حسابك.

رؤوس المصادقة

دعونا نراجع عناوين المصادقة المتوفرة للاستخدام مع خدمات Azure الذكاء الاصطناعي بسرعة.

الرأس	‏‏الوصف
Ocp-Apim-Subscription-Key	استخدم هذا العنوان للمصادقة باستخدام مفتاح مورد لخدمة معينة أو مفتاح مورد متعدد الخدمات.
Ocp-Apim-Subscription-Region	هذا العنوان مطلوب فقط عند استخدام مفتاح مورد متعدد الخدمات مع خدمة المترجم. استخدم هذا العنوان لتحديد منطقة المورد.
التخويل	استخدم هذا الرأس إذا كنت تستخدم رمز وصول. يتم تفصيل خطوات إجراء تبادل الرمز المميز في الأقسام التالية. القيمة المقدمة تتبع هذا التنسيق: Bearer <TOKEN>.

المصادقة باستخدام مفتاح مورد خدمة واحدة

الخيار الأول هو مصادقة طلب باستخدام مفتاح مورد لخدمة معينة، مثل المترجم. تتوفر المفاتيح في مدخل Microsoft Azure لكل مورد قمت بإنشائه. لاستخدام مفتاح مورد لمصادقة طلب، يجب تمريره كعنوان Ocp-Apim-Subscription-Key .

توضح هذه الطلبات النموذجية كيفية استخدام Ocp-Apim-Subscription-Key العنوان. ضع في اعتبارك أنه عند استخدام هذه العينة، ستحتاج إلى تضمين مفتاح مورد صالح.

هذا نموذج لاستدعاء خدمة المترجم:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

يوضح الفيديو التالي استخدام مفتاح خدمات Azure الذكاء الاصطناعي.

المصادقة باستخدام مفتاح مورد متعدد الخدمات

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

يتم توفير مفتاح المورد في كل طلب كعنوان Ocp-Apim-Subscription-Key .

المناطق المدعومة

عند استخدام مفتاح المورد متعدد الخدمات لتقديم طلب إلى api.cognitive.microsoft.com، يجب تضمين المنطقة في عنوان URL. على سبيل المثال: westus.api.cognitive.microsoft.com.

عند استخدام مفتاح مورد متعدد الخدمات مع Azure الذكاء الاصطناعي المترجم، يجب تحديد منطقة المورد مع Ocp-Apim-Subscription-Region العنوان.

يتم دعم المصادقة متعددة الخدمات في هذه المناطق:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2
• francecentral
• koreacentral
• northcentralus
• southafricanorth
• uaenorth
• switzerlandnorth

طلبات نموذج

هذا نموذج لاستدعاء خدمة المترجم:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Ocp-Apim-Subscription-Region: YOUR_SUBSCRIPTION_REGION' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

المصادقة باستخدام رمز الوصول

تقبل بعض خدمات Azure الذكاء الاصطناعي، وفي بعض الحالات تتطلب، رمز وصول مميزا. حالياً، تدعم هذه الخدمات رموز الوصول:

• واجهة برمجة تطبيقات ترجمة النصوص
• خدمات الكلام: واجهة برمجة تطبيقات تحويل الكلام إلى نص
• خدمات الكلام: واجهة برمجة تطبيقات تحويل النص إلى كلام

إشعار

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

تحذير

قد تتغير الخدمات التي تدعم رموز الوصول بمرور الوقت، يرجى التحقق من مرجع API للخدمة قبل استخدام طريقة المصادقة هذه.

يمكن استبدال كل من الخدمة الفردية ومفاتيح الموارد متعددة الخدمات بالرموز المميزة للمصادقة. رموز المصادقة صالحة لمدة 10 دقائق. يتم تخزينها بتنسيق JSON Web Token (JWT) ويمكن الاستعلام عنها برمجياً باستخدام مكتبات JWT.

يتم تضمين رموز الوصول في الطلب كرأس Authorization. يجب أن تكون قيمة الرمز المميز المقدمة مسبوقة بـ Bearer، على سبيل المثال: Bearer YOUR_AUTH_TOKEN.

طلبات نموذج

استخدم عنوان URL هذا لتبادل مفتاح مورد الرموز المميزة للوصول: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken.

curl -v -X POST \
"https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

تدعم هذه المناطق متعددة الخدمات تبادل الرموز:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2

بعد الحصول على رمز وصول، ستحتاج إلى تمريره في كل طلب كرأس Authorization. هذا نموذج لاستدعاء خدمة المترجم:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

المصادقة باستخدام معرف Microsoft Entra

هام

يجب دائما استخدام مصادقة Microsoft Entra مع اسم المجال الفرعي المخصص لمورد Azure. لا تدعم نقاط النهاية الإقليمية مصادقة Microsoft Entra.

في الأقسام السابقة، أوضحنا لك كيفية المصادقة مقابل خدمات Azure الذكاء الاصطناعي باستخدام خدمة واحدة أو مفتاح اشتراك متعدد الخدمات. بينما توفر هذه المفاتيح مساراً سريعاً وسهلاً لبدء التطوير، فإنها تقصر في السيناريوهات الأكثر تعقيداً التي تتطلب التحكم في الوصول المستند إلى الدور في Azure (Azure RBAC). لنلق نظرة على ما هو مطلوب للمصادقة باستخدام معرف Microsoft Entra.

في الأقسام التالية، ستستخدم إما بيئة Azure Cloud Shell أو Azure CLI لإنشاء مجال فرعي وتعيين الأدوار والحصول على رمز حامل للاتصال بخدمات Azure الذكاء الاصطناعي. إذا واجهتك مشكلة، فسيتم توفير الروابط في كل قسم مع جميع الخيارات المتاحة لكل أمر في Azure Cloud Shell/Azure CLI.

هام

إذا كانت مؤسستك تقوم بالمصادقة من خلال معرف Microsoft Entra، فيجب عليك تعطيل المصادقة المحلية (المصادقة باستخدام المفاتيح) بحيث يجب على المستخدمين في المؤسسة دائما استخدام معرف Microsoft Entra.

إنشاء مورد بنطاق فرعي مخصص

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

1. ابدأ بفتح Azure Cloud Shell. ثم حدد اشتراكاً:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. بعد ذلك، قم بإنشاء مورد خدمات Azure الذكاء الاصطناعي مع مجال فرعي مخصص. يجب أن يكون اسم المجال الفرعي فريداً بشكل عام ولا يمكن أن يتضمن أحرفاً خاصة، مثل: "."، "!"، "،".

   $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
   

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

تعيين دور لمدير الخدمة

الآن بعد أن أصبح لديك مجال فرعي مخصص مرتبط بموردك، ستحتاج إلى تعيين دور لمدير الخدمة.

إشعار

ضع في عين الاعتبار أن تعيينات دور Azure قد تستغرق ما يصل إلى خمس دقائق للنشر.

1. أولا، دعنا نسجل تطبيق Microsoft Entra.

   $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force
   
   $app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword
   

   ستحتاج إلى ApplicationId في الخطوة التالية.

2. بعد ذلك، تحتاج إلى إنشاء كيان خدمة لتطبيق Microsoft Entra.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   إشعار

   إذا قمت بتسجيل تطبيق في مدخل Microsoft Azure، فسيتم إكمال هذه الخطوة نيابةً عنك.

3. الخطوة الأخيرة هي تعيين دور "مستخدم الخدمات المعرفية" لمدير الخدمة (المحدد إلى المورد). من خلال تعيين دور، فإنك تمنح حق الوصول الكياني للخدمة إلى هذا المورد. يمكنك منح نفس الوصول الكياني للخدمة إلى موارد متعددة في اشتراكك.

   إشعار

   يتم استخدام ObjectId لكيان الخدمة، وليس ObjectId للتطبيق. سيكون ACCOUNT_ID هو معرف مورد Azure لحساب خدمات Azure الذكاء الاصطناعي الذي أنشأته. يمكنك العثور على معرف مورد Azure من "خصائص" المورد في مدخل Microsoft Azure.

   New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
   

نموذج الطلب

في هذا النموذج، يتم استخدام كلمة مرور للمصادقة على كيان الخدمة. ثم يتم استخدام الرمز المميز الموفر للاتصال بواجهة برمجة تطبيقات Computer Vision.

1. احصل على TenantId:

   $context=Get-AzContext
   $context.Tenant.Id
   

2. احصل على رمز مميز:

   $tenantId = $context.Tenant.Id
   $clientId = $app.ApplicationId
   $clientSecret = "<YOUR_PASSWORD>"
   $resourceUrl = "https://cognitiveservices.azure.com/"
   
   $tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
   $body = @{
       grant_type    = "client_credentials"
       client_id     = $clientId
       client_secret = $clientSecret
       resource      = $resourceUrl
   }
   
   $responseToken = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body
   $accessToken = $responseToken.access_token
   

   إشعار

   في أي وقت تستخدم فيه كلمات المرور في برنامج نصي، يكون الخيار الأكثر أمانا هو استخدام وحدة PowerShell Secrets Management والتكامل مع حل مثل Azure KeyVault.

3. اتصل بواجهة برمجة تطبيقات Computer Vision:

   $url = $account.Endpoint+"vision/v1.0/models"
   $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"="Bearer $accessToken"} -Verbose
   $result | ConvertTo-Json
   

بدلاً من ذلك، يمكن مصادقة مدير الخدمة بشهادة. بالإضافة إلى كيان الخدمة، يتم دعم كيان المستخدم أيضا من خلال وجود أذونات مفوضة من خلال تطبيق Microsoft Entra آخر. في هذه الحالة، بدلاً من كلمات المرور أو الشهادات، سيُطلب من المستخدمين المصادقة الثنائية عند الحصول على رمز مميز.

تخويل الوصول إلى هويات مدارة

تدعم خدمات Azure الذكاء الاصطناعي مصادقة Microsoft Entra مع الهويات المدارة لموارد Azure. يمكن للهويات المدارة لموارد Azure تخويل الوصول إلى موارد خدمات Azure الذكاء الاصطناعي باستخدام بيانات اعتماد Microsoft Entra من التطبيقات التي تعمل في أجهزة Azure الظاهرية (VMs) وتطبيقات الوظائف ومجموعات مقياس الجهاز الظاهري والخدمات الأخرى. باستخدام الهويات المدارة لموارد Azure مع مصادقة Microsoft Entra، يمكنك تجنب تخزين بيانات الاعتماد مع التطبيقات التي تعمل في السحابة.

تمكين الهويات المُدارة على جهاز ظاهري

قبل أن تتمكن من استخدام الهويات المدارة لموارد Azure لتخويل الوصول إلى موارد خدمات Azure الذكاء الاصطناعي من الجهاز الظاهري، يجب تمكين الهويات المدارة لموارد Azure على الجهاز الظاهري. لمعرفة كيفية تمكين الهويات المُدارة لـAzure Resources، راجع:

• مدخل Microsoft Azure
• Azure PowerShell
• Azure CLI
• قالب Azure Resource Manager
• مكتبات عميل Azure Resource Manager

لمزيد من المعلومات حول الهويات المدارة، راجع الهويات المدارة لموارد Azure.

استخدام Azure key vault للوصول إلى بيانات الاعتماد بأمان

يمكنك استخدام Azure Key Vault لتطوير تطبيقات خدمات Azure الذكاء الاصطناعي بشكل آمن. يمكنك Key Vault من تخزين بيانات اعتماد المصادقة في السحابة، ويقلل من فرص تسرب الأسرار عن طريق الخطأ، لأنك لن تخزن معلومات الأمان في التطبيق الخاص بك.

تتم المصادقة عبر معرف Microsoft Entra. يمكن إجراء التفويض عبر التحكم في الوصول المستند إلى الدور Azure (Azure RBAC) أو سياسة الوصول إلى مخزن المفاتيح. يمكن استخدام Azure RBAC لكل من إدارة الخزائن والوصول إلى البيانات المخزنة في المخزن، في حين لا يمكن استخدام سياسة الوصول إلى مخزن المفتاح إلا عند محاولة الوصول إلى البيانات المخزنة في المخزن.

(راجع أيضًا )

• ما هي خدمات Azure الذكاء الاصطناعي؟
• تسعير خدمات Azure الذكاء الاصطناعي
• المجالات الفرعية المخصصة