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 s více službami.
Klíč prostředku můžete získat z webu Azure Portal po vytvoření účtu.
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.
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 Translator. Klíče jsou k dispozici na webu Azure Portal pro každý prostředek, který jste vytvořili. Pokud chcete k ověření požadavku použít klíč prostředku, musíte ho předat jako hlavičku Ocp-Apim-Subscription-Key
.
Tyto ukázkové požadavky ukazují, jak použít hlavičku Ocp-Apim-Subscription-Key
. Mějte na paměti, že při použití této ukázky budete muset zahrnout platný klíč prostředku.
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
Následující video ukazuje použití klíče služeb Azure AI.
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 s více službami k provedení požadavku api.cognitive.microsoft.com
na , musíte zahrnout oblast do adresy URL. 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
.
Víceslužné ověřování se podporuje 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 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č
Poznámka:
Služba QnA Maker také používá autorizační hlavičku, ale vyžaduje klíč koncového bodu. Další informace najdete v tématu QnA Maker: Získání odpovědi z znalostní báze.
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 Bearer
napří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 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.
Začněte otevřením Azure Cloud Shellu. Pak vyberte předplatné:
Set-AzContext -SubscriptionName <SubscriptionName>
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>
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.
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.
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.
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.
Získejte ID tenanta:
$context=Get-AzContext $context.Tenant.Id
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 KeyVault.
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é
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro