Kérések hitelesítése a Foundry Tools eszközeihez

Az Öntödei eszközökhöz irányuló minden kérésnek tartalmaznia kell egy hitelesítési fejlécet. Ez a fejléc egy erőforráskulcs vagy hitelesítési jogkivonat mentén halad át, amely egy szolgáltatás vagy szolgáltatáscsoport előfizetésének ellenőrzésére szolgál. Ebben a cikkben megismerheti a kérések hitelesítésének három módját, valamint az egyes kérelmekre vonatkozó követelményeket.

Előfeltételek

Mielőtt kérést intéz, szüksége lesz egy Azure-előfizetésre és egy Foundry-erőforrásra. Ha Foundry-erőforrásra van szüksége, tekintse meg a foundry erőforrás-útmutatót .

Hitelesítési fejlécek

Tekintsük át gyorsan az Foundry Toolshoz használható hitelesítési fejléceket.

Fejléc Leírás
Ocp-Apim-Subscription-Key Ez a fejléc szolgáltatáskulccsal vagy egy Foundry erőforráskulccsal történő hitelesítéshez használható.
Ocp-Apim-Subscription-Region Ez a fejléc csak akkor szükséges, ha Foundry erőforrás-kulcsot használ az Azure Translatorral. Ezzel a fejléccel adhatja meg az erőforrás-régiót.
Engedélyezés Használja ezt a fejlécet, ha hozzáférési jogkivonatot használ. A jogkivonatok cseréjének lépéseit a következő szakaszokban találja. A megadott érték a következő formátumot követi: Bearer <TOKEN>.

Hitelesítés egyszolgáltatásos erőforráskulcs használatával

Az első lehetőség egy kérés hitelesítése egy adott szolgáltatás erőforráskulcsával, például az Azure Translatorrel. A kulcsok az Azure Portalon érhetők el minden létrehozott erőforráshoz. Nyissa meg az erőforrást az Azure Portalon. A Kulcsok > végpont szakasz az Erőforrás-kezelés szakaszban található. Másolja ki a végpontot és a hozzáférési kulcsot, mivel mindkettőre szüksége lesz az API-hívások hitelesítéséhez. A következők bármelyikét használhatja: KEY1 vagy KEY2. A két kulcs mindig lehetővé teszi a kulcsok biztonságos elforgatását és újragenerálását anélkül, hogy szolgáltatáskimaradást okoz.

Ha erőforráskulcsot szeretne használni egy kérés hitelesítéséhez, azt fejlécként Ocp-Apim-Subscription-Key kell továbbítani. Ez egy mintahívás az Azure Translator szolgáltatáshoz:

Ez egy mintahívás a Translator szolgáltatáshoz:

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

Hitelesítés Foundry-erőforráskulcs használatával

Egy Foundry-erőforráskulcs használatával hitelesítheti a kéréseket több Foundry-eszköz esetében. A hitelesítési hitelesítő adatok nincsenek egy adott szolgáltatáshoz kötve. A regionális rendelkezésre állással, a támogatott funkciókkal és a díjszabással kapcsolatos információkért tekintse meg az Foundry Tools díjszabását .

Az erőforráskulcsot minden kérés fejlécként Ocp-Apim-Subscription-Key adja meg.

Támogatott régiók

Ha a Foundry kulcsot használja a api.cognitive.microsoft.com-hez való kéréshez, a régiót meg kell adnia az URL-ben. Például: westus.api.cognitive.microsoft.com

Ha Foundry-erőforráskulcsot használ az Azure Translatorral, meg kell adnia az erőforrás-régiót a Ocp-Apim-Subscription-Region fejlécben.

Az öntödei erőforrások hitelesítése ezekben a régiókban támogatott:

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

Mintakérések

Ez egy mintahívás az Azure Translator szolgáltatáshoz:

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

Hitelesítés hozzáférési jogkivonattal

Egyes Foundry-eszközök elfogadnak és bizonyos esetekben hozzáférési jogkivonatot igényelnek. Jelenleg ezek a szolgáltatások támogatják a hozzáférési jogkivonatokat:

  • Szövegalapú fordítási API
  • Beszédek: Speech to text API
  • Beszédek: Szöveg–beszéd API

Figyelmeztetés

A hozzáférési jogkivonatokat támogató szolgáltatások idővel változhatnak, ezért a hitelesítési módszer használata előtt ellenőrizze a szolgáltatás API-referenciáit.

Az Foundry és az AI-szolgáltatások erőforráskulcsai hitelesítési jogkivonatokra cserélhetők. A hitelesítési jogkivonatok 10 percig érvényesek. JSON Web Token (JWT) formátumban vannak tárolva, és programozott módon kérdezhetők le a JWT-kódtárak használatával.

A hozzáférési jogkivonatok fejlécként szerepelnek a Authorization kérésekben. A megadott jogkivonat értékét meg kell előznie Bearer, például: Bearer YOUR_AUTH_TOKEN.

Mintakérések

Ezzel az URL-címvel erőforráskulcsot cserélhet egy hozzáférési jogkivonatra: 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"

Ezek a régiók támogatják az Foundry-erőforrások jogkivonat-cseréjét:

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

Miután beszerezte a hozzáférési jogkivonatot, minden kérésben át kell adnia azt Authorization fejlécként. Ez egy mintahívás az Azure Translator szolgáltatáshoz:

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

Hitelesítés Microsoft Entra ID-vel

Fontos

A Microsoft Entra-hitelesítést mindig az Azure-erőforrás egyéni altartománynevével együtt kell használni. A regionális végpontok nem támogatják a Microsoft Entra-hitelesítést.

Az előző szakaszokban bemutattuk, hogyan hitelesíthet API-kulcsokkal. Bár ezek a kulcsok gyors és egyszerű utat biztosítanak a fejlesztés megkezdéséhez, az azure-beli szerepköralapú hozzáférés-vezérlést (Azure RBAC) igénylő forgatókönyvekben nem állnak rendelkezésre. Vessünk egy pillantást a Microsoft Entra-azonosítóval történő biztonságosabb hitelesítéshez szükséges tudnivalókra.

A következő szakaszokban az Azure Cloud Shell-környezetet vagy az Azure CLI-t fogja használni egy altartomány létrehozásához, szerepkörök hozzárendeléséhez és egy tulajdonosi jogkivonat beszerzéséhez az Foundry Tools meghívásához. Ha elakad, az egyes szakaszokban hivatkozásokat talál az Azure Cloud Shell/Azure CLI egyes parancsaihoz elérhető összes lehetőséggel.

Fontos

Ha a szervezet a Microsoft Entra-azonosítón keresztül végez hitelesítést, tiltsa le a helyi hitelesítést (kulcsokkal történő hitelesítést), hogy a szervezet felhasználói mindig a Microsoft Entra-azonosítót használják.

Erőforrás létrehozása egyéni altartomány használatával

Az első lépés egy egyéni altartomány létrehozása. Ha olyan meglévő Foundry-erőforrást szeretne használni, amely nem rendelkezik egyéni altartománynévvel, kövesse az Foundry Tools egyéni altartományainak utasításait az egyéni altartományok engedélyezéséhez az erőforráshoz.

  1. Először nyissa meg az Azure Cloud Shellt. Ezután válasszon ki egy előfizetést:

    Set-AzContext -SubscriptionName <SubscriptionName>

  2. Ezután hozzon létre egy Foundry-erőforrást egy egyéni altartománnyal. Az altartomány nevének globálisan egyedinek kell lennie, és nem tartalmazhat speciális karaktereket, például: ".", "!", ",".

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

  3. Ha sikeres, a végpontnak az erőforrásra egyedi altartománynevet kell megjelenítenie.

Szerepkör hozzárendelése szolgáltatásnévhez

Most, hogy egyéni altartomány van társítva az erőforráshoz, szerepkört kell hozzárendelnie egy szolgáltatásnévhez.

Feljegyzés

Ne feledje, hogy az Azure-szerepkör-hozzárendelések propagálása akár öt percet is igénybe vehet.

  1. Először regisztráljunk egy Microsoft Entra-alkalmazást.

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

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

    A következő lépésben szüksége lesz az ApplicationId azonosítóra .

  2. Ezután létre kell hoznia egy szolgáltatásnevet a Microsoft Entra-alkalmazáshoz.

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>

    Feljegyzés

    Ha regisztrál egy alkalmazást az Azure Portalon, ez a lépés befejeződik.

  3. Az utolsó lépés a "Cognitive Services-felhasználó" szerepkör hozzárendelése a szolgáltatásnévhez (az erőforrás hatóköre). Szerepkör hozzárendelésével szolgáltatásnév-hozzáférést biztosít ehhez az erőforráshoz. Ugyanahhoz a szolgáltatásnévhez több erőforráshoz is hozzáférést adhat az előfizetésében.

    Feljegyzés

    A rendszer a szolgáltatásnév ObjectId azonosítóját használja, nem az alkalmazás ObjectId azonosítóját. A ACCOUNT_ID a létrehozott Foundry-erőforrás Azure-erőforrás-azonosítója lesz. Az Azure-erőforrás-azonosítót az erőforrás tulajdonságaiból találja az Azure Portalon.

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

Mintakérelem

Ebben a példában egy jelszóval hitelesíti a szolgáltatásnevet. A megadott token ezután az Azure Vision API meghívására szolgál.

  1. A TenantId lekérése:

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

  2. Jogkivonat lekérése:

    $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

    Feljegyzés

    Amikor jelszavakat használ egy szkriptben, a legbiztonságosabb megoldás a PowerShell Titkos kódok kezelése modul használata, és integrálható egy olyan megoldással, mint az Azure Key Vault.

  3. Az Azure Vision API meghívása:

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

Másik lehetőségként a szolgáltatásnév hitelesítése tanúsítványsal is lehetséges. A szolgáltatásnév mellett a felhasználónevét is támogatja egy másik Microsoft Entra-alkalmazáson keresztül delegált engedélyek. Ebben az esetben jelszavak vagy tanúsítványok helyett a rendszer kétfaktoros hitelesítést kér a felhasználóktól a jogkivonat beszerzésekor.

Felügyelt identitásokhoz való hozzáférés engedélyezése

A Foundry Tools támogatja a Microsoft Entra-hitelesítést az Azure-erőforrások felügyelt identitásaival. Az Azure-erőforrások felügyelt identitásai a Microsoft Entra hitelesítő adataival engedélyezhetik a Foundry erőforrásokhoz való hozzáférést az Azure-beli virtuális gépeken, függvényalkalmazásokban, virtuálisgép-méretezési csoportokban és egyéb szolgáltatásokban futó alkalmazásokból. Ha felügyelt identitásokat használ az Azure-erőforrásokhoz a Microsoft Entra-hitelesítéssel együtt, elkerülheti a hitelesítő adatok tárolását a felhőben futó alkalmazásokkal.

Felügyelt identitások engedélyezése virtuális gépen

Mielőtt felügyelt identitásokat használhat az Azure-erőforrásokhoz a virtuális gépről származó Foundry-erőforrásokhoz való hozzáférés engedélyezéséhez, engedélyeznie kell a felügyelt identitásokat a virtuális gépen lévő Azure-erőforrásokhoz. A felügyelt identitások Azure-erőforrásokhoz való engedélyezéséről a következő témakörben olvashat:

A felügyelt identitásokról további információt az Azure-erőforrások felügyelt identitásai című témakörben talál.

Hitelesítő adatok biztonságos elérése az Azure Key Vault használatával

Az Azure Key Vault használatával biztonságosan fejleszthet Microsoft Foundry-alkalmazásokat. A Key Vault lehetővé teszi a hitelesítési hitelesítő adatok felhőben való tárolását, és csökkenti annak esélyét, hogy a titkos kulcsok véletlenül kiszivárogjanak, mert nem fogja tárolni a biztonsági adatokat az alkalmazásban.

A hitelesítés a Microsoft Entra-azonosítón keresztül történik. Az engedélyezés azure-beli szerepköralapú hozzáférés-vezérléssel (Azure RBAC) vagy Key Vault hozzáférési szabályzattal végezhető el. Az Azure RBAC a tárolók kezelésére és a tárolóban tárolt adatok elérésére egyaránt használható, míg a Key Vault hozzáférési szabályzata csak a tárolóban tárolt adatok elérésének megkísérlésekor használható.

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: