Azure AI hizmetlerine yönelik isteklerin kimliğini doğrulama

Azure AI hizmetine yapılan her istek bir kimlik doğrulama üst bilgisi içermelidir. Bu üst bilgi, bir hizmet veya hizmet grubu için aboneliğinizi doğrulamak için kullanılan bir kaynak anahtarı veya kimlik doğrulama belirteci ile birlikte geçer. Bu makalede, bir isteğin kimliğini doğrulamanın üç yolu ve her birinin gereksinimleri hakkında bilgi edineceksiniz.

• Tek hizmetli veya çok hizmetli bir kaynak anahtarıyla kimlik doğrulaması yapma
• Belirteçle kimlik doğrulaması
• Microsoft Entra Kimliği ile kimlik doğrulaması

Önkoşullar

İstekte bulunmadan önce bir Azure hesabına ve azure yapay zeka hizmetleri aboneliğine ihtiyacınız vardır. Zaten bir hesabınız varsa devam edin ve sonraki bölüme geçin. Hesabınız yoksa birkaç dakika içinde ayarlamanızı sağlamak için bir kılavuzumuz vardır: Çok hizmetli kaynak oluşturma.

Hesabınızı oluşturduktan sonra Azure portalından kaynak anahtarınızı alabilirsiniz.

Kimlik doğrulama üst bilgileri

Şimdi Azure AI hizmetleriyle kullanılabilen kimlik doğrulama üst bilgilerini hızla gözden geçirelim.

Üst bilgi	Açıklama
Ocp-Apim-Subscription-Key	Belirli bir hizmetin veya çok hizmetli bir kaynak anahtarının kaynak anahtarıyla kimlik doğrulaması yapmak için bu üst bilgiyi kullanın.
Ocp-Apim-Subscription-Region	Bu üst bilgi yalnızca Çeviri hizmetiyle çok hizmetli bir kaynak anahtarı kullanılırken gereklidir. Kaynak bölgesini belirtmek için bu üst bilgiyi kullanın.
Yetkilendirme	Erişim belirteci kullanıyorsanız bu üst bilgiyi kullanın. Belirteç değişimi gerçekleştirme adımları aşağıdaki bölümlerde ayrıntılı olarak anlatılır. Sağlanan değer şu biçimdedir: Bearer <TOKEN>.

Tek hizmetli bir kaynak anahtarıyla kimlik doğrulaması yapma

İlk seçenek, Çeviri gibi belirli bir hizmetin kaynak anahtarıyla bir isteğin kimliğini doğrulamaktır. Anahtarlar, oluşturduğunuz her kaynak için Azure portalında kullanılabilir. Bir isteğin kimliğini doğrulamak için kaynak anahtarı kullanmak için üst bilgi olarak Ocp-Apim-Subscription-Key geçirilmelidir.

Bu örnek istekler, üst bilginin nasıl kullanılacağını Ocp-Apim-Subscription-Key gösterir. Bu örneği kullanırken geçerli bir kaynak anahtarı eklemeniz gerektiğini unutmayın.

Bu, Çeviri hizmetine örnek bir çağrıdır:

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

Aşağıdaki videoda Azure AI hizmetleri anahtarının kullanımı gösterilmektedir.

Çok hizmetli bir kaynak anahtarıyla kimlik doğrulaması yapma

İsteklerin kimliğini doğrulamak için çok hizmetli bir kaynak anahtarı kullanabilirsiniz. Temel fark, çok hizmetli kaynak anahtarının belirli bir hizmete bağlı olmadığıdır; bunun yerine birden çok Azure AI hizmetine yönelik isteklerin kimliğini doğrulamak için tek bir anahtar kullanılabilir. Bölgesel kullanılabilirlik, desteklenen özellikler ve fiyatlandırma hakkında bilgi için bkz. Azure AI hizmetleri fiyatlandırması.

Kaynak anahtarı her istekte üst bilgi olarak Ocp-Apim-Subscription-Key sağlanır.

Desteklenen bölgeler

'a istekte api.cognitive.microsoft.combulunmak için çok hizmetli kaynak anahtarını kullanırken URL'ye bölgeyi eklemeniz gerekir. Örneğin: westus.api.cognitive.microsoft.com.

Azure AI Çeviri ile çok hizmetli bir kaynak anahtarı kullanırken üst bilgiyle Ocp-Apim-Subscription-Region kaynak bölgesini belirtmeniz gerekir.

Çok hizmetli kimlik doğrulaması şu bölgelerde desteklenir:

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

Örnek istekler

Bu, Çeviri hizmetine örnek bir çağrıdır:

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

Erişim belirteci ile kimlik doğrulaması

Bazı Azure AI hizmetleri erişim belirtecini kabul ve bazı durumlarda gerektirir. Şu anda bu hizmetler erişim belirteçlerini desteklemektedir:

• Metin Çevirisi API'si
• Konuşma Hizmetleri: Konuşmayı metne dönüştürme API'si
• Konuşma Hizmetleri: Metin okuma API'si

Dekont

Soru-Cevap Oluşturma, Yetkilendirme üst bilgisini de kullanır, ancak bir uç nokta anahtarı gerektirir. Daha fazla bilgi için bkz. Soru-Cevap Oluşturma: bilgi bankası yanıt alma.

Uyarı

Erişim belirteçlerini destekleyen hizmetler zaman içinde değişebilir, lütfen bu kimlik doğrulama yöntemini kullanmadan önce hizmetin API başvurusunu denetleyin.

Kimlik doğrulama belirteçleri için hem tek hizmet hem de çok hizmetli kaynak anahtarları değiştirilebilir. Kimlik doğrulama belirteçleri 10 dakika boyunca geçerlidir. Bunlar JSON Web Belirteci (JWT) biçiminde depolanır ve JWT kitaplıkları kullanılarak program aracılığıyla sorgulanabilir.

Erişim belirteçleri bir isteğe üst bilgi olarak Authorization eklenir. Sağlanan belirteç değerinin Bearerönünde olmalıdır, örneğin: Bearer YOUR_AUTH_TOKEN.

Örnek istekler

Erişim belirteci için kaynak anahtarı değişimi yapmak için şu URL'yi kullanın: 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"

Bu çok hizmetli bölgeler belirteç değişimini destekler:

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

Erişim belirtecini aldıktan sonra her istekte üst bilgi olarak Authorization geçirmeniz gerekir. Bu, Çeviri hizmetine örnek bir çağrıdır:

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 ID ile kimlik doğrulaması

Önemli

Microsoft Entra kimlik doğrulamasının her zaman Azure kaynağınızın özel alt etki alanı adıyla birlikte kullanılması gerekir. Bölgesel uç noktalar Microsoft Entra kimlik doğrulamayı desteklemez.

Önceki bölümlerde, tek hizmetli veya çok hizmetli abonelik anahtarı kullanarak Azure AI hizmetlerinde kimlik doğrulamasını nasıl yapacağınızı gösterdik. Bu anahtarlar geliştirmeye başlamak için hızlı ve kolay bir yol sağlarken, Azure rol tabanlı erişim denetimi (Azure RBAC) gerektiren daha karmaşık senaryolarda yetersiz kalır. Şimdi Microsoft Entra Id kullanarak kimlik doğrulaması yapmak için gerekenlere göz atalım.

Aşağıdaki bölümlerde Bir alt etki alanı oluşturmak, roller atamak ve Azure AI hizmetlerini çağırmak için taşıyıcı belirteç almak için Azure Cloud Shell ortamını veya Azure CLI'yi kullanacaksınız. Takılırsanız, her bölümde Azure Cloud Shell/Azure CLI'daki her komut için tüm kullanılabilir seçenekleri içeren bağlantılar sağlanır.

Önemli

Kuruluşunuz Microsoft Entra Id aracılığıyla kimlik doğrulaması yapıyorsa, kuruluştaki kullanıcıların her zaman Microsoft Entra Id kullanması için yerel kimlik doğrulamasını (anahtarlarla kimlik doğrulama) devre dışı bırakmanız gerekir.

Özel alt etki alanı ile kaynak oluşturma

İlk adım, özel bir alt etki alanı oluşturmaktır. Özel alt etki alanı adı olmayan mevcut bir Azure AI hizmetleri kaynağını kullanmak istiyorsanız, kaynağınız için özel alt etki alanını etkinleştirmek için Azure AI hizmetleri özel alt etki alanları'ndaki yönergeleri izleyin.

1. Azure Cloud Shell'i açarak başlayın. Ardından bir abonelik seçin:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Ardından, özel bir alt etki alanıyla bir Azure AI hizmetleri kaynağı oluşturun. Alt etki alanı adının genel olarak benzersiz olması gerekir ve ".", "!", "," gibi özel karakterler içeremez.

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

3. Başarılı olursa, Uç Nokta kaynağınıza özgü alt etki alanı adını göstermelidir.

Hizmet sorumlusuna rol atama

Artık kaynağınızla ilişkilendirilmiş özel bir alt etki alanınız olduğuna göre, hizmet sorumlusuna bir rol atamanız gerekir.

Dekont

Azure rol atamalarının yayılması beş dakika kadar sürebilir.

1. İlk olarak bir Microsoft Entra uygulaması kaydedelim.

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

   Sonraki adımda ApplicationId'ye ihtiyacınız olacak.

2. Ardından, Microsoft Entra uygulaması için bir hizmet sorumlusu oluşturmanız gerekir.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Dekont

   Bir uygulamayı Azure portalına kaydederseniz, bu adım sizin için tamamlanır.

3. Son adım, hizmet sorumlusuna (kapsamı kaynak olarak belirlenmiş) "Bilişsel Hizmetler Kullanıcısı" rolünü atamaktır. Rol atayarak bu kaynağa hizmet sorumlusu erişimi verirsiniz. Aboneliğinizdeki birden çok kaynağa aynı hizmet sorumlusu erişimi vekleyebilirsiniz.

   Dekont

   Hizmet sorumlusunun ObjectId değeri, uygulamanın ObjectId değeri değil kullanılır. ACCOUNT_ID, oluşturduğunuz Azure AI hizmetleri hesabının Azure kaynak kimliği olacaktır. Azure portalında kaynağın "özellikleri" bölümünden Azure kaynak kimliğini bulabilirsiniz.

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

Örnek isteği

Bu örnekte, hizmet sorumlusunun kimliğini doğrulamak için bir parola kullanılır. Sağlanan belirteç daha sonra Görüntü İşleme API'sini çağırmak için kullanılır.

1. TenantId değerini alın:

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

2. Belirteç alma:

   $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
   

   Dekont

   Betikte parola kullandığınızda en güvenli seçenek PowerShell Gizli Dizi Yönetimi modülünü kullanmak ve Azure KeyVault gibi bir çözümle tümleştirmektir.

3. Görüntü İşleme API'sini çağırın:

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

Alternatif olarak, hizmet sorumlusunun kimliği bir sertifikayla doğrulanabilir. Hizmet sorumlusuna ek olarak, kullanıcı sorumlusu başka bir Microsoft Entra uygulaması aracılığıyla temsilci olarak atanan izinlere sahip olarak da desteklenir. Bu durumda, parolalar veya sertifikalar yerine, belirteç alırken kullanıcılardan iki öğeli kimlik doğrulaması istenir.

Yönetilen kimliklere erişimi yetkilendirme

Azure yapay zeka hizmetleri, Azure kaynakları için yönetilen kimliklerle Microsoft Entra kimlik doğrulamasını destekler. Azure kaynakları için yönetilen kimlikler, Azure sanal makinelerinde (VM' ler), işlev uygulamalarında, sanal makine ölçek kümelerinde ve diğer hizmetlerde çalışan uygulamalardan Microsoft Entra kimlik bilgilerini kullanarak Azure AI hizmetleri kaynaklarına erişim yetkisi verebilir. Azure kaynakları için yönetilen kimlikleri Microsoft Entra kimlik doğrulamasıyla birlikte kullanarak, kimlik bilgilerini bulutta çalışan uygulamalarınızla birlikte depolamaktan kaçınabilirsiniz.

VM'de yönetilen kimlikleri etkinleştirme

Vm'nizden Azure yapay zeka hizmetleri kaynaklarına erişim yetkisi vermek üzere Azure kaynakları için yönetilen kimlikleri kullanabilmeniz için önce VM'de Azure kaynakları için yönetilen kimlikleri etkinleştirmeniz gerekir. Azure Kaynakları için yönetilen kimlikleri etkinleştirmeyi öğrenmek için bkz:

• Azure portalındaki
• Azure PowerShell
• Azure CLI
• Azure Resource Manager şablonu
• Azure Resource Manager istemci kitaplıkları

Yönetilen kimlikler hakkında daha fazla bilgi için bkz . Azure kaynakları için yönetilen kimlikler.

Kimlik bilgilerine güvenli bir şekilde erişmek için Azure anahtar kasasını kullanma

Azure AI hizmetleri uygulamalarını güvenli bir şekilde geliştirmek için Azure Key Vault'u kullanabilirsiniz. Key Vault, kimlik doğrulama kimlik bilgilerinizi bulutta depolamanıza olanak tanır ve uygulamanızda güvenlik bilgilerini depolamayacağınız için gizli dizilerin yanlışlıkla sızdırılma olasılığını azaltır.

Kimlik doğrulaması Microsoft Entra Id aracılığıyla yapılır. Yetkilendirme, Azure rol tabanlı erişim denetimi (Azure RBAC) veya Key Vault erişim ilkesi aracılığıyla yapılabilir. Azure RBAC hem kasaların yönetimi hem de kasada depolanan erişim verileri için kullanılabilirken, anahtar kasası erişim ilkesi yalnızca kasada depolanan verilere erişmeye çalışırken kullanılabilir.

Ayrıca bkz.

• Azure yapay zeka hizmetleri nelerdir?
• Azure yapay zeka hizmetleri fiyatlandırması
• Özel alt etki alanları