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

  • Článek

Každý požadavek na službu Azure Cognitive Services musí obsahovat ověřovací hlavičku. Tato hlavička předává klíč předplatného 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 o požadavcích pro každý z nich.

Požadavky

Než začnete vyžadovat, potřebujete účet Azure a předplatné služeb Azure Cognitive Services. Pokud už účet máte, pokračujte a přejděte k další části. Pokud účet nemáte, máme pro vás průvodce nastavením v řádu minut: Vytvoření účtu služeb Cognitive Services pro Azure.

Klíč předplatného můžete získat z Azure Portal po vytvoření účtu.

Hlavičky ověřování

Pojďme si rychle projít hlavičky ověřování, které jsou k dispozici pro použití se službami Azure Cognitive Services.

Hlavička Popis
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 pro více služeb.
Ocp-Apim-Subscription-Region Tato hlavička je vyžadována pouze v případě, že se službou Translator používáte klíč předplatného pro více služeb. Pomocí této hlavičky můžete zadat oblast předplatného.
Autorizace Tuto hlavičku použijte, pokud používáte přístupový token. Postup výměny tokenů je 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ěřit požadavek pomocí klíče předplatného pro konkrétní službu, jako je Translator. Klíče jsou k dispozici v Azure Portal pro každý prostředek, který jste vytvořili. Pokud chcete k ověření požadavku použít klíč předplatného, musí se předat jako hlavička Ocp-Apim-Subscription-Key .

Tyto ukázkové požadavky ukazují, jak hlavičku Ocp-Apim-Subscription-Key použít. 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í

Klíč pro více služeb v současnosti nepodporuje: QnA Maker, Asistivní čtečka, Personalizace a Detektor anomálií.

Tato možnost také používá klíč předplatného k ověřování požadavků. Hlavní rozdíl spočívá v tom, že klíč předplatného není svázán s konkrétní službou, ale jeden klíč se dá 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 uvedený v každé žádosti jako hlavička Ocp-Apim-Subscription-Key .

Ukázka klíče předplatného pro více služeb pro Cognitive Services

Podporované oblasti

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

Při použití klíče předplatného pro více služeb se službou Translator musíte zadat oblast předplatného pomocí hlavičky Ocp-Apim-Subscription-Region .

Ověřování více služeb 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í přístupového tokenu

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

  • Rozhraní API pro překlad textu
  • Služby Speech: Rozhraní API pro převod řeči na text
  • Služby Speech: Rozhraní 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 z znalostní báze.

Upozornění

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.

Klíče předplatného pro jednu službu i pro více služeb je možné vyměnit za ověřovací tokeny. Ověřovací tokeny jsou platné po dobu 10 minut. Ukládají se 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é hodnotě tokenu musí předcházet , Bearernapříklad : Bearer YOUR_AUTH_TOKEN.

Ukázkové požadavky

Pomocí této adresy URL můžete vyměnit klíč předplatného za 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

Jakmile přístupový token získáte, budete ho muset předat v každé žádosti 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é

Azure AD ověřování je vždy potřeba použít společně s vlastním názvem subdomény vašeho prostředku Azure. Regionální koncové body nepodporují ověřování Azure AD.

V předchozích částech jsme vám ukázali, jak provést ověřování ve službách Azure Cognitive Services pomocí klíče předplatného pro jednu nebo více služeb. I když tyto klíče poskytují rychlou a jednoduchou cestu k zahájení vývoje, ve složitějších scénářích, které vyžadují řízení přístupu na základě role v Azure (Azure RBAC) jsou kratší. Pojďme se podívat, co je potřeba k ověřování pomocí Azure Active Directory (Azure AD).

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, najdete v každé části odkazy se všemi dostupnými možnostmi pro jednotlivé příkazy v Azure Cloud Shell 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, povolte pro svůj prostředek vlastní subdoménu podle pokynů v tématu Vlastní subdomény služeb Cognitive Services .

  1. Začněte otevřením Cloud Shell Azure. 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 se v koncovém bodu měl 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 instančnímu objektu přiřadit roli.

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 Azure AD.

    $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 ApplicationId .

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

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>

    Poznámka

    Pokud zaregistrujete aplikaci v Azure Portal, je tento krok dokončen 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 na prostředek). Přiřazením role udělujete instančnímu objektu přístup k tomuto prostředku. Stejný přístup k instančnímu objektu můžete udělit více prostředkům ve vašem předplatném.

    Poznámka

    Používá se ObjectId instančního objektu, 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í API Počítačové zpracování obrazu.

  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. Zavolejte 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ě je možné instanční objekt ověřit pomocí certifikátu. Kromě instančního objektu se objekt uživatele podporuje také tím, že má oprávnění delegovaná prostřednictvím jiné aplikace Azure AD. V takovém případě by se uživatelům místo hesel nebo certifikátů při získávání tokenu zobrazila výzva k dvojúrovňové 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 na virtuálních počítačích Azure, aplikacích funkcí, škálovacích sadách virtuálních počítačů a dalších službách. Používáním 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ů do aplikací, které běží v cloudu.

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

Než budete moct pomocí spravovaných identit pro prostředky Azure autorizovat přístup 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.

Zabezpečený přístup k přihlašovacím údajům pomocí služby Azure Key Vault

Azure Key Vault můžete použít k bezpečnému vývoji aplikací služeb Cognitive Services. 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 do aplikace neukládáte bezpečnostní informace.

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

Viz také