Aanvragen verifiëren voor Azure AI-services

Artikel
10/24/2023

Elke aanvraag voor een Azure AI-service moet een verificatieheader bevatten. Deze header geeft een resourcesleutel of verificatietoken door, dat wordt gebruikt om uw abonnement te valideren voor een service of groep services. In dit artikel vindt u meer informatie over drie manieren om een aanvraag en de vereisten voor elke aanvraag te verifiëren.

Verifiëren met een resourcesleutel voor één service of met meerdere services
Verifiëren met een token
Verifiëren met Microsoft Entra-id

Vereisten

Voordat u een aanvraag indient, hebt u een Azure-account en een Azure AI-servicesabonnement nodig. Als u al een account hebt, gaat u verder met de volgende sectie. Als u geen account hebt, hebben we een handleiding om u binnen enkele minuten in te stellen: Een resource voor meerdere services maken.

U kunt uw resourcesleutel ophalen uit Azure Portal nadat u uw account hebt gemaakt.

Verificatieheaders

Laten we snel de verificatieheaders bekijken die beschikbaar zijn voor gebruik met Azure AI-services.

Koptekst	Beschrijving
Ocp-Apim-Subscription-Key	Gebruik deze header om te verifiëren met een resourcesleutel voor een specifieke service of een resourcesleutel voor meerdere services.
Ocp-Apim-Subscription-Region	Deze header is alleen vereist wanneer u een resourcesleutel voor meerdere services gebruikt met de Vertalen-service. Gebruik deze header om de resourceregio op te geven.
Autorisatie	Gebruik deze header als u een toegangstoken gebruikt. De stappen voor het uitvoeren van een tokenuitwisseling worden beschreven in de volgende secties. De opgegeven waarde volgt deze notatie: `Bearer <TOKEN>`.

Verifiëren met een resourcesleutel met één service

De eerste optie is het verifiëren van een aanvraag met een resourcesleutel voor een specifieke service, zoals Vertalen. De sleutels zijn beschikbaar in Azure Portal voor elke resource die u hebt gemaakt. Als u een resourcesleutel wilt gebruiken om een aanvraag te verifiëren, moet deze worden doorgegeven als de Ocp-Apim-Subscription-Key header.

Deze voorbeeldaanvragen laten zien hoe u de Ocp-Apim-Subscription-Key header gebruikt. Houd er rekening mee dat u bij het gebruik van dit voorbeeld een geldige resourcesleutel moet opnemen.

Dit is een voorbeeld van een aanroep naar de Vertalen-service:

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

In de volgende video ziet u hoe u een Azure AI-servicessleutel gebruikt.

Verifiëren met een resourcesleutel voor meerdere services

U kunt een resourcesleutel voor meerdere services gebruiken om aanvragen te verifiëren. Het belangrijkste verschil is dat de resourcesleutel voor meerdere services niet is gekoppeld aan een specifieke service, maar een enkele sleutel kan worden gebruikt voor het verifiëren van aanvragen voor meerdere Azure AI-services. Zie prijzen voor Azure AI-services voor informatie over regionale beschikbaarheid, ondersteunde functies en prijzen.

De resourcesleutel wordt in elke aanvraag opgegeven als header Ocp-Apim-Subscription-Key .

Ondersteunde regio’s

Wanneer u de resourcesleutel voor meerdere services gebruikt om een aanvraag in te api.cognitive.microsoft.comdienen, moet u de regio in de URL opnemen. Voorbeeld: westus.api.cognitive.microsoft.com.

Wanneer u een resourcesleutel voor meerdere services gebruikt met Azure AI Vertalen, moet u de resourceregio opgeven met de Ocp-Apim-Subscription-Region header.

Verificatie met meerdere services wordt ondersteund in deze regio's:

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

Voorbeeldaanvragen

Dit is een voorbeeld van een aanroep naar de Vertalen-service:

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

Verifiëren met een toegangstoken

Sommige Azure AI-services accepteren, en in sommige gevallen is een toegangstoken vereist. Momenteel bieden deze services ondersteuning voor toegangstokens:

Tekstomzettings-API
Speech Services: Spraak-naar-tekst-API
Speech Services: Tekst-naar-spraak-API

Notitie

QnA Maker maakt ook gebruik van de autorisatieheader, maar vereist een eindpuntsleutel. Zie QnA Maker: Antwoord ophalen uit knowledge base voor meer informatie.

Waarschuwing

De services die toegangstokens ondersteunen, kunnen na verloop van tijd veranderen. Raadpleeg de API-verwijzing voor een service voordat u deze verificatiemethode gebruikt.

Zowel één service als resourcesleutels voor meerdere services kunnen worden uitgewisseld voor verificatietokens. Verificatietokens zijn 10 minuten geldig. Ze worden opgeslagen in JSON Web Token-indeling (JWT) en kunnen programmatisch worden opgevraagd met behulp van de JWT-bibliotheken.

Toegangstokens worden als header Authorization opgenomen in een aanvraag. De opgegeven tokenwaarde moet worden voorafgegaan door Bearerbijvoorbeeld: Bearer YOUR_AUTH_TOKEN.

Voorbeeldaanvragen

Gebruik deze URL om een resourcesleutel uit te wisselen voor een toegangstoken: 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"

Deze regio's met meerdere services ondersteunen tokenuitwisseling:

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

Nadat u een toegangstoken hebt opgehaald, moet u deze in elke aanvraag doorgeven als de Authorization header. Dit is een voorbeeld van een aanroep naar de Vertalen-service:

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

Verifiëren met Microsoft Entra ID

Belangrijk

Microsoft Entra-verificatie moet altijd samen met de aangepaste subdomeinnaam van uw Azure-resource worden gebruikt. Regionale eindpunten bieden geen ondersteuning voor Microsoft Entra-verificatie.

In de vorige secties hebt u laten zien hoe u zich kunt verifiëren bij Azure AI-services met behulp van een abonnementssleutel met één service of een abonnementssleutel voor meerdere services. Hoewel deze sleutels een snel en eenvoudig pad bieden om te beginnen met ontwikkelen, vallen ze kort in complexere scenario's waarvoor op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) is vereist. Laten we eens kijken wat er nodig is om te verifiëren met behulp van Microsoft Entra-id.

In de volgende secties gebruikt u de Azure Cloud Shell-omgeving of de Azure CLI om een subdomein te maken, rollen toe te wijzen en een bearer-token te verkrijgen om de Azure AI-services aan te roepen. Als u vastloopt, vindt u koppelingen in elke sectie met alle beschikbare opties voor elke opdracht in Azure Cloud Shell/Azure CLI.

Belangrijk

Als uw organisatie verificatie uitvoert via Microsoft Entra-id, moet u lokale verificatie uitschakelen (verificatie met sleutels), zodat gebruikers in de organisatie altijd Microsoft Entra-id moeten gebruiken.

Een resource maken met een aangepast subdomein

De eerste stap is het maken van een aangepast subdomein. Als u een bestaande Azure AI-servicesresource wilt gebruiken die geen aangepaste subdomeinnaam heeft, volgt u de instructies in aangepaste subdomeinen van Azure AI-services om aangepast subdomein voor uw resource in te schakelen.

Begin met het openen van Azure Cloud Shell. Selecteer vervolgens een abonnement:
```
Set-AzContext -SubscriptionName <SubscriptionName>
```

Maak vervolgens een Azure AI-servicesresource met een aangepast subdomein. De naam van het subdomein moet globaal uniek zijn en mag geen speciale tekens bevatten, zoals: ".", "!", ",".

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

Als dit lukt, moet op het eindpunt de naam van het subdomein worden weergegeven die uniek is voor uw resource.

Een rol toewijzen aan een service-principal

Nu u een aangepast subdomein hebt gekoppeld aan uw resource, moet u een rol toewijzen aan een service-principal.

Notitie

Houd er rekening mee dat het maximaal vijf minuten kan duren voordat Azure-roltoewijzingen zijn doorgegeven.

Laten we eerst een Microsoft Entra-toepassing registreren.

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

$app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword

U hebt de ApplicationId nodig in de volgende stap.

Vervolgens moet u een service-principal maken voor de Microsoft Entra-toepassing.
```
New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
```
Notitie

Als u een toepassing registreert in Azure Portal, wordt deze stap voor u voltooid.
De laatste stap is het toewijzen van de rol Cognitive Services-gebruiker aan de service-principal (gericht op de resource). Door een rol toe te wijzen, verleent u service-principal toegang tot deze resource. U kunt dezelfde service-principal toegang verlenen tot meerdere resources in uw abonnement.

Notitie

De ObjectId van de service-principal wordt gebruikt, niet de ObjectId voor de toepassing. De ACCOUNT_ID is de Azure-resource-id van het Azure AI-servicesaccount dat u hebt gemaakt. U vindt de Azure-resource-id in de 'eigenschappen' van de resource in Azure Portal.
```
New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
```

Voorbeeldaanvraag

In dit voorbeeld wordt een wachtwoord gebruikt om de service-principal te verifiëren. Het opgegeven token wordt vervolgens gebruikt om de Computer Vision-API aan te roepen.

Haal uw TenantId op:

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

Een token ophalen:

$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

Notitie

Wanneer u wachtwoorden in een script gebruikt, is de veiligste optie om de Module PowerShell Secrets Management te gebruiken en te integreren met een oplossing zoals Azure KeyVault.

De Computer Vision-API aanroepen:

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

U kunt de service-principal ook verifiëren met een certificaat. Naast een service-principal wordt de gebruikers-principal ook ondersteund door machtigingen die zijn gedelegeerd via een andere Microsoft Entra-toepassing. In dit geval wordt gebruikers in plaats van wachtwoorden of certificaten gevraagd om tweeledige verificatie bij het verkrijgen van een token.

Toegang tot beheerde identiteiten autoriseren

Azure AI-services ondersteunen Microsoft Entra-verificatie met beheerde identiteiten voor Azure-resources. Beheerde identiteiten voor Azure-resources kunnen toegang verlenen tot Azure AI-servicesbronnen met behulp van Microsoft Entra-referenties van toepassingen die worden uitgevoerd in virtuele Azure-machines (VM's), functie-apps, virtuele-machineschaalsets en andere services. Door beheerde identiteiten te gebruiken voor Azure-resources samen met Microsoft Entra-verificatie, kunt u voorkomen dat referenties worden opgeslagen met uw toepassingen die in de cloud worden uitgevoerd.

Beheerde identiteiten inschakelen op een VIRTUELE machine

Voordat u beheerde identiteiten voor Azure-resources kunt gebruiken om toegang te verlenen tot Azure AI-services-resources vanaf uw VM, moet u beheerde identiteiten inschakelen voor Azure-resources op de VM. Zie voor meer informatie over het inschakelen van beheerde identiteiten voor Azure-resources:

Zie Beheerde identiteiten voor Azure-resources voor meer informatie over beheerde identiteiten.

Azure Key Vault gebruiken om veilig toegang te krijgen tot referenties

U kunt Azure Key Vault gebruiken om veilig Toepassingen voor Azure AI-services te ontwikkelen. Met Key Vault kunt u uw verificatiereferenties opslaan in de cloud en vermindert u de kans dat geheimen per ongeluk worden gelekt, omdat u geen beveiligingsgegevens in uw toepassing opslaat.

Verificatie wordt uitgevoerd via Microsoft Entra-id. Autorisatie kan worden uitgevoerd via op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) of Key Vault-toegangsbeleid. Azure RBAC kan worden gebruikt voor zowel het beheer van de kluizen als voor toegang tot gegevens die zijn opgeslagen in een kluis, terwijl toegangsbeleid voor key vault alleen kan worden gebruikt wanneer u toegang probeert te krijgen tot gegevens die zijn opgeslagen in een kluis.

Aanvragen verifiëren voor Azure AI-services

Vereisten

Verificatieheaders

Verifiëren met een resourcesleutel met één service

Verifiëren met een resourcesleutel voor meerdere services

Ondersteunde regio’s

Voorbeeldaanvragen

Verifiëren met een toegangstoken

Voorbeeldaanvragen

Verifiëren met Microsoft Entra ID

Een resource maken met een aangepast subdomein

Een rol toewijzen aan een service-principal

Voorbeeldaanvraag

Toegang tot beheerde identiteiten autoriseren

Beheerde identiteiten inschakelen op een VIRTUELE machine

Azure Key Vault gebruiken om veilig toegang te krijgen tot referenties

Zie ook

Aanvullende resources