Ověřování požadavků na služby Azure AI

Každý požadavek na službu Azure AI musí obsahovat hlavičku ověřování. Tato hlavička předává klíč prostředku nebo ověřovací token, který slouží k ověření předplatného pro službu nebo skupinu služeb. V tomto článku se dozvíte o třech způsobech ověření žádosti a požadavků pro každý z nich.

• Ověřování pomocí klíče prostředku s jednou službou nebo více službami
• Ověření pomocí tokenu
• Ověřování pomocí ID Microsoft Entra

Požadavky

Před provedením požadavku potřebujete účet Azure a předplatné služeb Azure AI. Pokud už účet máte, přejděte k další části. Pokud účet nemáte, máme průvodce, který vás provede nastavením během několika minut: Vytvoření prostředku služeb Azure AI.

Na webu Azure Portal přejděte ke svému prostředku. Oddíl Klíče a koncový bod najdete v části Správa prostředků. Zkopírujte koncový bod a přístupový klíč, protože budete potřebovat obojí pro ověřování volání rozhraní API. Použít můžete předponu KEY1 nebo KEY2. Vždy mít dva klíče vám umožní bezpečně otáčet a znovu vygenerovat klíče, aniž by to způsobilo přerušení služeb.

Hlavičky ověřování

Pojďme se rychle podívat na hlavičky ověřování, které jsou k dispozici pro použití se službami Azure AI.

Hlavička	Popis
Ocp-Apim-Subscription-Key	Tato hlavička slouží k ověření pomocí klíče prostředku pro konkrétní službu nebo klíč prostředku s více službami.
Ocp-Apim-Subscription-Region	Tato hlavička se vyžaduje jenom v případě, že se službou Azure AI Translator používá klíč prostředku s více službami. Pomocí této hlavičky zadejte oblast prostředků.
Autorizace	Tuto hlavičku použijte, pokud používáte přístupový token. Kroky k provedení výměny tokenů jsou podrobně popsané v následujících částech. Hodnota zadaná v tomto formátu: Bearer <TOKEN>.

Ověřování pomocí klíče prostředku s jednou službou

První možností je ověření požadavku pomocí klíče prostředku pro konkrétní službu, jako je Azure AI Translator. Klíče jsou k dispozici na webu Azure Portal pro každý prostředek, který jste vytvořili. Na webu Azure Portal přejděte ke svému prostředku. Oddíl Klíče a koncový bod najdete v části Správa prostředků. Zkopírujte koncový bod a přístupový klíč, protože budete potřebovat obojí pro ověřování volání rozhraní API. Použít můžete předponu KEY1 nebo KEY2. Vždy mít dva klíče vám umožní bezpečně otáčet a znovu vygenerovat klíče, aniž by to způsobilo přerušení služeb.

Pokud chcete k ověření požadavku použít klíč prostředku, musíte ho předat jako hlavičku Ocp-Apim-Subscription-Key . Toto je ukázkové volání služby Azure AI Translator:

Toto je ukázkové volání služby 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

Ověřování pomocí klíče prostředku s více službami

K ověření požadavků můžete použít klíč prostředku s více službami . Hlavní rozdíl spočívá v tom, že klíč prostředku s více službami není svázaný s konkrétní službou, ale k ověřování požadavků na více služeb Azure AI je možné použít jeden klíč. Informace o regionální dostupnosti, podporovaných funkcích a cenách najdete v cenách služeb Azure AI.

Klíč prostředku je k dispozici v každém požadavku jako hlavička Ocp-Apim-Subscription-Key .

Podporované oblasti

Při použití klíče prostředku služby Azure AI pro více služeb k provedení požadavku api.cognitive.microsoft.commusíte do adresy URL zahrnout oblast. Například: westus.api.cognitive.microsoft.com.

Při použití klíče prostředku s více službami s Azure AI Translator je nutné zadat oblast prostředků s hlavičkou Ocp-Apim-Subscription-Region .

Ověřování prostředků s více službami je podporováno v těchto oblastech:

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

Ukázkové požadavky

Toto je ukázkové volání služby Azure AI 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

Ověřování pomocí přístupového tokenu

Některé služby Azure AI přijímají přístupový token a v některých případech vyžadují přístupový token. V současné době tyto služby podporují přístupové tokeny:

• Rozhraní API pro překlad textu
• Speech Services: Rozhraní API pro převod řeči na text
• Speech Services: Rozhraní API pro převod textu na řeč

Upozorňující

Služby, které podporují přístupové tokeny, se můžou v průběhu času měnit. Než použijete tuto metodu ověřování, zkontrolujte referenční informace k rozhraní API pro službu.

Pro ověřovací tokeny je možné vyměnit klíče prostředků s jednou službou i více službami. Ověřovací tokeny jsou platné 10 minut. Jsou uložené ve formátu JSON Web Token (JWT) a dají se dotazovat programově pomocí knihoven JWT.

Přístupové tokeny jsou součástí požadavku jako hlavička Authorization . Zadaná hodnota tokenu musí předcházet Bearernapříklad: Bearer YOUR_AUTH_TOKEN.

Ukázkové požadavky

Tuto adresu URL použijte k výměně klíče prostředku pro přístupový token: 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"

Tyto oblasti s více službami podporují výměnu tokenů:

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

Po získání přístupového tokenu ho budete muset předat v každém požadavku jako hlavičku Authorization . Toto je ukázkové volání služby Azure AI 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

Ověřování pomocí Microsoft Entra ID

Důležité

Ověřování Microsoft Entra musí být vždy použito společně s vlastním názvem subdomény vašeho prostředku Azure. Regionální koncové body nepodporují ověřování Microsoft Entra.

V předchozích částech jsme vám ukázali, jak se ověřovat ve službách Azure AI pomocí klíče předplatného s jednou službou nebo více službami. I když tyto klíče poskytují rychlou a snadnou cestu k zahájení vývoje, spadají do složitějších scénářů, které vyžadují řízení přístupu na základě role v Azure (Azure RBAC). Pojďme se podívat, co je potřeba k ověření pomocí ID Microsoft Entra.

V následujících částech použijete prostředí Azure Cloud Shell nebo Azure CLI k vytvoření subdomény, přiřazení rolí a získání nosný token pro volání služeb Azure AI. Pokud se zaseknete, v každé části se zobrazí odkazy se všemi dostupnými možnostmi pro každý příkaz v Azure Cloud Shellu nebo Azure CLI.

Důležité

Pokud vaše organizace provádí ověřování prostřednictvím Microsoft Entra ID, měli byste zakázat místní ověřování (ověřování pomocí klíčů), aby uživatelé v organizaci měli vždy používat Microsoft Entra ID.

Vytvoření prostředku s vlastní subdoménou

Prvním krokem je vytvoření vlastní subdomény. Pokud chcete použít existující prostředek služeb Azure AI, který nemá vlastní název subdomény, postupujte podle pokynů ve vlastních subdoménách služeb Azure AI a povolte vlastní subdoménu pro váš prostředek.

1. Začněte otevřením Azure Cloud Shellu. Pak vyberte předplatné:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Dále vytvořte prostředek služeb Azure AI s vlastní subdoménou. Název subdomény musí být globálně jedinečný a nesmí obsahovat speciální znaky, například: ".", "!", ",".

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

3. V případě úspěchu by měl koncový bod zobrazit název subdomény jedinečný pro váš prostředek.

Přiřazení role instančnímu objektu

Teď, když máte vlastní subdoménu přidruženou k vašemu prostředku, budete muset přiřadit roli instančnímu objektu.

Poznámka:

Mějte na paměti, že rozšíření přiřazení rolí Azure může trvat až pět minut.

1. Nejprve zaregistrujeme aplikaci Microsoft Entra.

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

   V dalším kroku budete potřebovat ID aplikace.

2. Dále musíte vytvořit instanční objekt pro aplikaci Microsoft Entra.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Poznámka:

   Pokud zaregistrujete aplikaci na webu Azure Portal, dokončí se tento krok za vás.

3. Posledním krokem je přiřazení role Uživatel služeb Cognitive Services k instančnímu objektu (vymezenému prostředku). Přiřazením role udělujete instančnímu objektu přístup k tomuto prostředku. Stejnému instančnímu objektu můžete udělit přístup k více prostředkům ve vašem předplatném.

   Poznámka:

   ObjectId instančního objektu se používá, nikoli ObjectId pro aplikaci. ACCOUNT_ID bude ID prostředku Azure účtu služeb Azure AI, který jste vytvořili. ID prostředku Azure najdete ve vlastnostech prostředku na webu Azure Portal.

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

Ukázkový požadavek

V této ukázce se k ověření instančního objektu používá heslo. Poskytnutý token se pak použije k volání rozhraní API Počítačové zpracování obrazu.

1. Získejte ID tenanta:

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

2. Získání tokenu:

   $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
   

   Poznámka:

   Kdykoli ve skriptu používáte hesla, nejbezpečnější možností je použít modul Pro správu tajných kódů PowerShellu a integrovat je s řešením, jako je Azure Key Vault.

3. Volání rozhraní API Počítačové zpracování obrazu:

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

Případně se instanční objekt dá ověřit pomocí certifikátu. Kromě instančního objektu se instanční objekt podporuje také tím, že má oprávnění delegovaná prostřednictvím jiné aplikace Microsoft Entra. V takovém případě se uživatelům místo hesel nebo certifikátů při získávání tokenu zobrazí výzva k dvoufaktorovému ověřování.

Autorizace přístupu ke spravovaným identitám

Služby Azure AI podporují ověřování Microsoft Entra se spravovanými identitami pro prostředky Azure. Spravované identity pro prostředky Azure můžou autorizovat přístup k prostředkům služeb Azure AI pomocí přihlašovacích údajů Microsoft Entra z aplikací spuštěných ve virtuálních počítačích Azure, aplikací funkcí, škálovacích sad virtuálních počítačů a dalších služeb. Pomocí spravovaných identit pro prostředky Azure společně s ověřováním Microsoft Entra se můžete vyhnout ukládání přihlašovacích údajů s aplikacemi, které běží v cloudu.

Povolení spravovaných identit na virtuálním počítači

Abyste mohli používat spravované identity pro prostředky Azure k autorizaci přístupu k prostředkům služeb Azure AI z virtuálního počítače, musíte na virtuálním počítači povolit spravované identity pro prostředky Azure. Informace o povolení spravovaných identit pro prostředky Azure najdete tady:

• Azure Portal
• Azure PowerShell
• Azure CLI
• Šablona Azure Resource Manageru
• Klientské knihovny Azure Resource Manageru

Další informace o spravovaných identitách najdete v tématu Spravované identity pro prostředky Azure.

Použití služby Azure Key Vault k bezpečnému přístupu k přihlašovacím údajům

Azure Key Vault můžete použít k bezpečnému vývoji aplikací služeb Azure AI. Key Vault umožňuje ukládat přihlašovací údaje pro ověřování v cloudu a snižuje riziko náhodného úniku tajných kódů, protože v aplikaci neukládáte bezpečnostní údaje.

Ověřování se provádí prostřednictvím MICROSOFT Entra ID. Autorizace se může provádět prostřednictvím řízení přístupu na základě role (Azure RBAC) nebo zásad přístupu ke službě Key Vault. Azure RBAC se dá použít pro správu trezorů i přístupových dat uložených v trezoru, zatímco zásady přístupu trezoru klíčů se dají použít jenom při pokusu o přístup k datům uloženým v trezoru.

Viz také

• Co jsou služby Azure AI?
• Ceny služeb Azure AI
• Vlastní subdomény