Uwierzytelnianie żądań w usługach Azure AI

Każde żądanie do usługi Azure AI musi zawierać nagłówek uwierzytelniania. Ten nagłówek przechodzi wzdłuż klucza zasobu lub tokenu uwierzytelniania, który służy do weryfikowania subskrypcji dla usługi lub grupy usług. W tym artykule poznasz trzy sposoby uwierzytelniania żądania i wymagania dotyczące każdego z nich.

• Uwierzytelnianie za pomocą klucza zasobu z jedną usługą lub wieloma usługami
• Uwierzytelnianie przy użyciu tokenu
• Uwierzytelnianie przy użyciu identyfikatora Entra firmy Microsoft

Wymagania wstępne

Przed wykonaniem żądania potrzebne jest konto platformy Azure i subskrypcja usług Azure AI. Jeśli masz już konto, przejdź do następnej sekcji. Jeśli nie masz konta, zapoznaj się z przewodnikiem dotyczącym konfigurowania w ciągu kilku minut: Tworzenie zasobu z wieloma usługami.

Klucz zasobu można pobrać z witryny Azure Portal po utworzeniu konta.

Nagłówki uwierzytelniania

Szybko przejrzyjmy nagłówki uwierzytelniania dostępne do użycia z usługami azure AI.

Nagłówek	opis
Ocp-Apim-Subscription-Key	Użyj tego nagłówka, aby uwierzytelnić się przy użyciu klucza zasobu dla określonej usługi lub klucza zasobu z wieloma usługami.
Ocp-Apim-Subscription-Region	Ten nagłówek jest wymagany tylko w przypadku używania klucza zasobu z wieloma usługami w usłudze Translator. Użyj tego nagłówka, aby określić region zasobu.
Autoryzacja	Użyj tego nagłówka, jeśli używasz tokenu dostępu. Kroki przeprowadzania wymiany tokenów zostały szczegółowo opisane w poniższych sekcjach. Podana wartość ma następujący format: Bearer <TOKEN>.

Uwierzytelnianie przy użyciu klucza zasobu pojedynczej usługi

Pierwszą opcją jest uwierzytelnienie żądania przy użyciu klucza zasobu dla określonej usługi, takiej jak Translator. Klucze są dostępne w witrynie Azure Portal dla każdego utworzonego zasobu. Aby użyć klucza zasobu do uwierzytelniania żądania, należy przekazać go wraz z nagłówkiem Ocp-Apim-Subscription-Key .

Te przykładowe żądania pokazują, jak używać nagłówka Ocp-Apim-Subscription-Key . Należy pamiętać, że w przypadku korzystania z tego przykładu należy uwzględnić prawidłowy klucz zasobu.

Jest to przykładowe wywołanie usługi 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

W poniższym filmie wideo pokazano, jak używać klucza usług azure AI.

Uwierzytelnianie przy użyciu klucza zasobu z wieloma usługami

Do uwierzytelniania żądań można użyć klucza zasobu z wieloma usługami . Główną różnicą jest to, że klucz zasobu z wieloma usługami nie jest powiązany z określoną usługą, a pojedynczy klucz może służyć do uwierzytelniania żądań dla wielu usług azure AI. Zobacz Cennik usług azure AI, aby uzyskać informacje o dostępności regionalnej, obsługiwanych funkcjach i cenach.

Klucz zasobu jest udostępniany w każdym żądaniu Ocp-Apim-Subscription-Key jako nagłówek.

Obsługiwane regiony

W przypadku używania klucza zasobu z wieloma usługami w celu wysłania żądania do api.cognitive.microsoft.comadresu URL należy uwzględnić region. Na przykład: westus.api.cognitive.microsoft.com.

W przypadku korzystania z klucza zasobu z wieloma usługami w usłudze Azure AI Translator należy określić region zasobu z nagłówkiem Ocp-Apim-Subscription-Region .

Uwierzytelnianie wieloskładnikowe jest obsługiwane w następujących regionach:

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

Przykładowe żądania

Jest to przykładowe wywołanie usługi 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

Uwierzytelnianie przy użyciu tokenu dostępu

Niektóre usługi sztucznej inteligencji platformy Azure akceptują i w niektórych przypadkach wymagają tokenu dostępu. Obecnie te usługi obsługują tokeny dostępu:

• Interfejs API tłumaczenia tekstu
• Usługi rozpoznawania mowy: interfejs API zamiany mowy na tekst
• Usługi rozpoznawania mowy: interfejs API zamiany tekstu na mowę

Uwaga

Usługa QnA Maker używa również nagłówka Autoryzacja, ale wymaga klucza punktu końcowego. Aby uzyskać więcej informacji, zobacz QnA Maker: Uzyskiwanie odpowiedzi z baza wiedzy.

Ostrzeżenie

Usługi obsługujące tokeny dostępu mogą ulec zmianie w czasie. Przed użyciem tej metody uwierzytelniania sprawdź dokumentację interfejsu API dla usługi.

Zarówno pojedynczej usługi, jak i kluczy zasobów z wieloma usługami można wymieniać na potrzeby tokenów uwierzytelniania. Tokeny uwierzytelniania są ważne przez 10 minut. Są one przechowywane w formacie JSON Web Token (JWT) i mogą być odpytywane programowo przy użyciu bibliotek JWT.

Tokeny dostępu są dołączane do żądania jako nagłówka Authorization . Podana wartość tokenu musi być poprzedzona wartością Bearer, na przykład : Bearer YOUR_AUTH_TOKEN.

Przykładowe żądania

Użyj tego adresu URL, aby wymienić klucz zasobu dla tokenu dostępu: 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"

Te regiony z wieloma usługami obsługują wymianę tokenów:

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

Po otrzymaniu tokenu dostępu należy przekazać je w każdym żądaniu Authorization jako nagłówek. Jest to przykładowe wywołanie usługi 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

Uwierzytelnianie przy użyciu usługi Microsoft Entra ID

Ważne

Uwierzytelnianie Entra firmy Microsoft zawsze musi być używane razem z niestandardową nazwą poddomeny zasobu platformy Azure. Regionalne punkty końcowe nie obsługują uwierzytelniania entra firmy Microsoft.

W poprzednich sekcjach pokazano, jak uwierzytelniać się w usługach azure AI przy użyciu klucza subskrypcji pojedynczej usługi lub wielu usług. Chociaż te klucze zapewniają szybką i łatwą ścieżkę do rozpoczęcia programowania, brakuje im bardziej złożonych scenariuszy, które wymagają kontroli dostępu opartej na rolach platformy Azure (Azure RBAC). Przyjrzyjmy się temu, co jest wymagane do uwierzytelnienia przy użyciu identyfikatora Entra firmy Microsoft.

W poniższych sekcjach użyjesz środowiska usługi Azure Cloud Shell lub interfejsu wiersza polecenia platformy Azure, aby utworzyć poddomenę, przypisać role i uzyskać token elementu nośnego w celu wywołania usług Azure AI. Jeśli utkniesz, linki są udostępniane w każdej sekcji z wszystkimi dostępnymi opcjami dla każdego polecenia w usłudze Azure Cloud Shell/interfejsie wiersza polecenia platformy Azure.

Ważne

Jeśli Organizacja przeprowadza uwierzytelnianie za pomocą identyfikatora Entra firmy Microsoft, należy wyłączyć uwierzytelnianie lokalne (uwierzytelnianie przy użyciu kluczy), aby użytkownicy w organizacji zawsze musieli używać identyfikatora Entra firmy Microsoft.

Tworzenie zasobu z niestandardową poddomeną

Pierwszym krokiem jest utworzenie niestandardowej poddomeny. Jeśli chcesz użyć istniejącego zasobu usług Azure AI, który nie ma niestandardowej nazwy poddomeny, postępuj zgodnie z instrukcjami w temacie Niestandardowe poddomeny usług Azure AI, aby włączyć niestandardową poddomenę zasobu.

1. Zacznij od otwarcia usługi Azure Cloud Shell. Następnie wybierz subskrypcję:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Następnie utwórz zasób usług Azure AI z niestandardową poddomeną. Nazwa poddomeny musi być globalnie unikatowa i nie może zawierać znaków specjalnych, takich jak: ".", "!", ",".

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

3. W przypadku powodzenia punkt końcowy powinien wyświetlić nazwę poddomeny unikatową dla zasobu.

Przypisywanie roli do jednostki usługi

Teraz, po utworzeniu niestandardowej poddomeny skojarzonej z zasobem, musisz przypisać rolę do jednostki usługi.

Uwaga

Pamiętaj, że propagacja przypisań ról platformy Azure może potrwać do pięciu minut.

1. Najpierw zarejestrujmy aplikację Firmy Microsoft Entra.

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

   W następnym kroku będziesz potrzebować identyfikatora ApplicationId .

2. Następnie należy utworzyć jednostkę usługi dla aplikacji Microsoft Entra.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Uwaga

   Jeśli zarejestrujesz aplikację w witrynie Azure Portal, ten krok zostanie ukończony.

3. Ostatnim krokiem jest przypisanie roli "Użytkownik usług Cognitive Services" do jednostki usługi (w zakresie do zasobu). Przypisując rolę, udzielasz jednostce usługi dostępu do tego zasobu. Możesz udzielić tej samej jednostki usługi dostępu do wielu zasobów w ramach subskrypcji.

   Uwaga

   Identyfikator ObjectId jednostki usługi jest używany, a nie identyfikator ObjectId dla aplikacji. ACCOUNT_ID będzie identyfikatorem zasobu platformy Azure utworzonego konta usług Azure AI. Identyfikator zasobu platformy Azure można znaleźć w sekcji "properties" zasobu w witrynie Azure Portal.

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

Przykładowe żądanie

W tym przykładzie hasło jest używane do uwierzytelniania jednostki usługi. Podany token jest następnie używany do wywoływania interfejsu API przetwarzanie obrazów.

1. Pobierz identyfikator dzierżawy:

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

2. Uzyskiwanie 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
   

   Uwaga

   Za każdym razem, gdy używasz haseł w skrypcie, najbezpieczniejszą opcją jest użycie modułu Zarządzania wpisami tajnymi programu PowerShell i integracja z rozwiązaniem, takim jak Azure KeyVault.

3. Wywołaj interfejs API przetwarzanie obrazów:

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

Alternatywnie jednostkę usługi można uwierzytelnić przy użyciu certyfikatu. Oprócz jednostki usługi jednostka użytkownika jest również obsługiwana przez delegowanie uprawnień za pośrednictwem innej aplikacji Firmy Microsoft Entra. W takim przypadku zamiast haseł lub certyfikatów użytkownicy będą monitowani o uwierzytelnianie dwuskładnikowe podczas uzyskiwania tokenu.

Autoryzowanie dostępu do tożsamości zarządzanych

Usługi azure AI obsługują uwierzytelnianie firmy Microsoft Entra przy użyciu tożsamości zarządzanych dla zasobów platformy Azure. Tożsamości zarządzane dla zasobów platformy Azure mogą autoryzować dostęp do zasobów usług azure AI przy użyciu poświadczeń firmy Microsoft z aplikacji działających na maszynach wirtualnych platformy Azure, aplikacjach funkcji, zestawach skalowania maszyn wirtualnych i innych usługach. Korzystając z tożsamości zarządzanych dla zasobów platformy Azure wraz z uwierzytelnianiem firmy Microsoft Entra, można uniknąć przechowywania poświadczeń z aplikacjami uruchomionymi w chmurze.

Włączanie tożsamości zarządzanych na maszynie wirtualnej

Aby można było użyć tożsamości zarządzanych dla zasobów platformy Azure w celu autoryzowania dostępu do zasobów usług azure AI z maszyny wirtualnej, musisz włączyć tożsamości zarządzane dla zasobów platformy Azure na maszynie wirtualnej. Aby dowiedzieć się, jak włączyć tożsamości zarządzane dla zasobów platformy Azure, zobacz:

• Azure Portal
• Azure PowerShell
• Interfejs wiersza polecenia platformy Azure
• Szablon usługi Azure Resource Manager
• Biblioteki klienta usługi Azure Resource Manager

Aby uzyskać więcej informacji na temat tożsamości zarządzanych, zobacz Tożsamości zarządzane dla zasobów platformy Azure.

Bezpieczne uzyskiwanie dostępu do poświadczeń przy użyciu usługi Azure Key Vault

Za pomocą usługi Azure Key Vault można bezpiecznie opracowywać aplikacje usług Azure AI. Usługa Key Vault umożliwia przechowywanie poświadczeń uwierzytelniania w chmurze i zmniejsza prawdopodobieństwo przypadkowego wycieku wpisów tajnych, ponieważ nie będziesz przechowywać informacji zabezpieczających w aplikacji.

Uwierzytelnianie odbywa się za pośrednictwem identyfikatora Entra firmy Microsoft. Autoryzacja może odbywać się za pomocą kontroli dostępu opartej na rolach (RBAC) platformy Azure lub zasad dostępu usługi Key Vault. Kontrola dostępu oparta na rolach platformy Azure może służyć zarówno do zarządzania magazynami, jak i uzyskiwania dostępu do danych przechowywanych w magazynie, podczas gdy zasady dostępu do magazynu kluczy mogą być używane tylko podczas próby uzyskania dostępu do danych przechowywanych w magazynie.

Zobacz też

• Co to są usługi Azure AI?
• Cennik usług azure AI
• Niestandardowe poddomeny