مصادقة الطلبات إلى الخدمات المعرفية Azure

  • مقالة
  • قراءة خلال 7 دقائق

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

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

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

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

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

دعنا نراجع بسرعة رؤوس المصادقة المتوفرة للاستخدام مع Azure Cognitive Services.

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

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

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

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

هذه عينة استدعاء إلى واجهة برمجة تطبيقات بحث الويب Bing:

curl -X GET 'https://api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

هذه عينة من المكالمات إلى خدمة المترجم:

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

يوضح الفيديو التالي استخدام مفتاح الخدمات المعرفية.

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

تحذير

في الوقت الحالي، لا يدعم المفتاح متعدد الخدمات: صانع QnA القارئ الشامل وPersonalizer و Anomaly Detector.

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

يتم توفير مفتاح الاشتراك في كل طلب كرأس Ocp-Apim-Subscription-Key .

Multi-service subscription key demonstration for Cognitive Services

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

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

عند استخدام مفتاح الاشتراك متعدد الخدمات مع الخدمة المترجم، يجب تحديد منطقة الاشتراك باستخدام 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

طلبات عينات

هذه عينة استدعاء إلى واجهة برمجة تطبيقات بحث الويب Bing:

curl -X GET 'https://YOUR-REGION.api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

هذه عينة من المكالمات إلى خدمة المترجم:

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 المعرفية، وفي بعض الحالات تتطلب، رمزا مميزا للمصادقة. حاليا، تدعم هذه الخدمات الرموز المميزة للمصادقة:

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

ملاحظة

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

تحذير

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

يمكن استبدال كل من مفاتيح الاشتراك في الخدمة الواحدة ومتعددة الخدمات برموز المصادقة. رموز المصادقة صالحة لمدة 10 دقائق.

يتم تضمين الرموز المميزة للمصادقة في الطلب كرأس 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

المصادقة باستخدام (دليل Azure النشط) AAD

هام

يجب دائما استخدام مصادقة AAD (دليل Azure النشط) مع اسم المجال الفرعي المخصص لمورد Azure الخاص بك. لا تدعم نقاط النهاية الإقليمية مصادقة AAD (دليل Azure النشط).

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

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

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

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

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

    Set-AzContext -SubscriptionName <SubscriptionName>

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

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

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

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

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

ملاحظة

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

  1. أولا ، دعنا نسجل طلبا AAD (دليل Azure النشط).

    $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force

$app = New-AzADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -Password $SecureStringPassword

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

  2. بعد ذلك ، تحتاج إلى إنشاء مدير خدمة للتطبيق AAD (دليل Azure النشط).

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>

    ملاحظة

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

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

    ملاحظة

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

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

طلب عينة

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

  1. احصل على معرف المستأجر الخاص بك:

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

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

    ملاحظة

    إذا كنت تستخدم Azure Cloud Shell، فهذا يعني أن SecureClientSecret الفئة غير متوفرة.

    $authContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList "https://login.windows.net/<TENANT_ID>"
$secureSecretObject = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.SecureClientSecret" -ArgumentList $SecureStringPassword   
$clientCredential = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential" -ArgumentList $app.ApplicationId, $secureSecretObject
$token=$authContext.AcquireTokenAsync("https://cognitiveservices.azure.com/", $clientCredential).Result
$token
  1. اتصل بواجهة برمجة تطبيقات رؤية الكمبيوتر:
    $url = $account.Endpoint+"vision/v1.0/models"
$result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"=$token.CreateAuthorizationHeader()} -Verbose
$result | ConvertTo-Json

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

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

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

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

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

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

راجع أيضًا