Ověřování požadavků ve službách Azure Cognitive Services

  • Článek
  • 7 min ke čtení

Každý požadavek na službu Azure Cognitive Service musí obsahovat hlavičku ověřování. Tato hlavička předává klíč předplatného nebo přístupový token, který slouží k ověření vašeho 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ždou z nich.

Požadavky

Před provedením žádosti potřebujete účet Azure a předplatné služby Azure Cognitive Services. Pokud už účet máte, přejděte k další části. Pokud účet nemáte, máme průvodce, který vám pomůže nastavit během několika minut: Vytvoření účtu Cognitive Services pro Azure.

Klíč předplatného 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 Cognitive Services.

Hlavička Description
Ocp-Apim-Subscription-Key Tato hlavička slouží k ověření pomocí klíče předplatného pro konkrétní službu nebo klíč předplatného s více službami.
Ocp-Apim-Subscription-Region Tato hlavička se vyžaduje jenom v případě, že se službou Translator používáte klíč předplatného s více službami. Pomocí této hlavičky určete oblast předplatného.
Autorizace Tuto hlavičku použijte, pokud používáte ověřovací token. Kroky k provedení výměny tokenů jsou podrobně popsané v následujících částech. Zadaná hodnota má tento formát: Bearer <TOKEN>.

Ověřování pomocí klíče předplatného s jednou službou

První možností je ověření požadavku pomocí klíče předplatného pro konkrétní službu, jako je Translator. Klíče jsou k dispozici na webu Azure Portal pro každý vytvořený prostředek. Pokud chcete k ověření požadavku použít klíč předplatného, musí být předán jako hlavička 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íč předplatného.

Toto je ukázkové volání rozhraní API Bingu pro vyhledávání na webu:

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

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 Cognitive Services.

Ověřování pomocí klíče předplatného s více službami

Upozornění

V tuto chvíli klíč s více službami nepodporuje: QnA Maker, Asistivní čtečku, personalizaci a detektor anomálií.

Tato možnost také používá klíč předplatného k ověření požadavků. Hlavní rozdíl spočívá v tom, že klíč předplatného není svázaný s konkrétní službou, místo toho lze jeden klíč použít k ověřování požadavků pro více služeb Cognitive Services. Informace o regionální dostupnosti, podporovaných funkcích a cenách najdete v tématu Ceny služeb Cognitive Services .

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

Multi-service subscription key demonstration for Cognitive Services

Podporované oblasti

Při použití klíče předplatného s více službami k provedení požadavku na api.cognitive.microsoft.com, musíte do adresy URL zahrnout oblast. Příklad: westus.api.cognitive.microsoft.com.

Při použití klíče předplatného více služeb se službou Translator je nutné zadat oblast předplatného 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í rozhraní API Bingu pro vyhledávání na webu:

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

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í ověřovacího tokenu

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

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

Poznámka

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 ze znalostní báze.

Upozornění

Služby, které podporují ověřovací 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.

Klíče předplatného s jednou službou i více službami je možné vyměnit za ověřovací tokeny. Ověřovací tokeny jsou platné po dobu 10 minut.

Ověřovací 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 předplatného pro ověřovací 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

Jakmile získáte ověřovací token, budete ho 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í Azure Active Directory

Důležité

Ověřování AAD se vždy musí používat společně s vlastním názvem subdomény vašeho prostředku Azure. Regionální koncové body nepodporují ověřování AAD.

V předchozích částech jsme vám ukázali, jak se ověřovat ve službách Azure Cognitive Services 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í Azure Active Directory (AAD).

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ého tokenu pro volání služeb Azure Cognitive Services. 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.

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 Cognitive Services, který nemá vlastní název subdomény, postupujte podle pokynů ve vlastních subdoménách služeb Cognitive Services 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 Cognitive Services 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 k prostředku přidruženou vlastní subdoménu, budete muset přiřadit roli instančnímu objektu.

Poznámka

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

  1. Nejprve zaregistrujeme aplikaci AAD.

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

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

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

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

    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 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 Cognitive Services, který jste vytvořili. ID prostředku Azure najdete ve vlastnostech prostředku v 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. Zadaný token se pak použije k volání rozhraní POČÍTAČOVÉ ZPRACOVÁNÍ OBRAZU API.

  1. Získejte ID tenanta:

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

  2. Získání tokenu:

    Poznámka

    Pokud používáte Azure Cloud Shell, SecureClientSecret třída není dostupná.

    $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. 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"=$token.CreateAuthorizationHeader()} -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é AAD aplikace. 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 Cognitive Services podporují ověřování Azure Active Directory (Azure AD) 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 Cognitive Services pomocí přihlašovacích údajů Azure AD 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 Azure AD se můžete vyhnout ukládání přihlašovacích údajů s vašimi aplikacemi, které běží v cloudu.

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

Než budete moct používat spravované identity pro prostředky Azure k autorizaci přístupu k prostředkům služeb Cognitive Services 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:

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

Viz také