التحقق من صحة الطلبات إلى أدوات الصابك

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

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

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

قبل أن تقدم طلبا، تحتاج إلى اشتراك في Azure ومورد في Foundry. إذا كنت بحاجة إلى مورد ل Foundry، راجع دليل إنشاء موارد Foundry .

عناوين المصادقة

دعونا نراجع بسرعة رؤوس المصادقة المتاحة للاستخدام مع أدوات Foundry.

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

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

الخيار الأول هو التحقق من صحة الطلب باستخدام مفتاح مورد لخدمة معينة، مثل Azure Translator. تتوفر المفاتيح في مدخل Microsoft Azure لكل مورد قمت بإنشائه. انتقل إلى مجموعة الموارد في مدخل Microsoft Azure. يمكن العثور على قسم Keys & Endpoint في قسم Resource Management . انسخ نقطة النهاية ومفتاح الوصول حيث ستحتاج إلى كليهما لمصادقة استدعاءات واجهة برمجة التطبيقات. يمكنك استخدام إما KEY1 أو KEY2. يسمح لك وجود مفتاحين دائماً بتدوير المفاتيح وإعادة إنشائها بأمان دون التسبب في تعطيل الخدمة.

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

هذه عينة استدعاء لخدمة Translator:

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

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

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

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

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

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

عند استخدام مفتاح موارد Foundry مع Azure Translator، يجب تحديد منطقة المورد مع الرأس 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

طلبات نموذج

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

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

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

بعض أدوات Foundry Tools، وفي بعض الحالات تتطلب، رمز الوصول. حاليا، تدعم هذه الخدمات رموز الوصول المميزة:

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

تحذير

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

يمكن استبدال مفاتيح موارد خدمات Foundry وخدمات الذكاء الاصطناعي برموز المصادقة. الرموز المميزة للمصادقة صالحة لمدة 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"

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

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

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

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 RBAC). دعونا نلقي نظرة على ما هو مطلوب للمصادقة بشكل أكثر أمانا باستخدام معرف Microsoft Entra.

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

مهم

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

إنشاء مورد مع مجال فرعي مخصص

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

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

   Set-AzContext -SubscriptionName <SubscriptionName>
   

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

   $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 (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 الخاص بمورد Foundry الذي أنشأته. يمكنك العثور على معرف مورد Azure من "خصائص" المورد في مدخل Microsoft Azure.

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

نموذج الطلب

في هذا النموذج، يتم استخدام كلمة مرور لمصادقة كيان الخدمة. يتم بعد ذلك استخدام الرمز المقدم لاستدعاء واجهة برمجة تطبيقات Azure 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 Key Vault.

3. استدعي واجهة برمجة تطبيقات Azure 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 آخر. في هذه الحالة، بدلا من كلمات المرور أو الشهادات، ستتم مطالبة المستخدمين بالمصادقة الثنائية عند الحصول على الرمز المميز.

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

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

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

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

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

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

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

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

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

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

• ما هي أدوات المسبك؟
• تسعير أدوات الصاهر
• المجالات الفرعية المخصصة