Mengautentikasi permintaan ke layanan Azure AI

2025-05-20

Setiap permintaan ke layanan Azure AI harus menyertakan header autentikasi. Header ini meneruskan kunci sumber daya atau token autentikasi, yang digunakan untuk memvalidasi langganan Anda untuk layanan atau grup layanan. Dalam artikel ini, Anda akan mempelajari tentang tiga cara untuk mengautentikasi permintaan dan persyaratan untuk masing-masing.

Autentikasi dengan layanan tunggal atau kunci sumber daya multi-layanan AI Foundry.
Mengautentikasi dengan token.
Autentikasi dengan ID Microsoft Entra.

Prasyarat

Sebelum membuat permintaan, Anda memerlukan langganan Azure dan sumber daya AI Foundry. Jika Anda memerlukan sumber daya AI Foundry, lihat panduan membuat sumber daya AI Foundry .

Header autentikasi

Mari kita tinjau header autentikasi yang tersedia untuk digunakan dengan layanan Azure AI dengan cepat.

Kepala Halaman	Deskripsi
Ocp-Apim-Subscription-Key	Gunakan header ini untuk mengautentikasi dengan kunci sumber daya untuk layanan tertentu atau kunci sumber daya AI Foundry.
Ocp-Apim-Subscription-Region	Header ini hanya diperlukan saat menggunakan kunci sumber daya AI Foundry dengan layanan Penerjemah Azure AI. Gunakan header ini untuk menentukan wilayah sumber daya.
Otorisasi	Gunakan header ini jika Anda menggunakan token akses. Langkah-langkah untuk melakukan pertukaran token dirinci di bagian berikut. Nilai yang diberikan mengikuti format ini: `Bearer <TOKEN>`.

Mengautentikasi dengan kunci sumber daya layanan tunggal

Opsi pertama adalah mengautentikasi permintaan dengan kunci sumber daya untuk layanan tertentu, seperti Penerjemah Azure AI. Kunci tersedia di portal Azure untuk setiap sumber daya yang telah Anda buat. Buka sumber daya Anda di portal Azure. Bagian Kunci & Titik Akhir dapat ditemukan di bagian Manajemen Sumber Daya. Salin titik akhir dan kunci akses Anda karena keduanya diperlukan untuk mengautentikasi panggilan API Anda. Anda dapat menggunakan KEY1 atau KEY2. Selalu miliki dua kunci untuk memungkinkan Anda memutar dan meregenerasi kunci dengan aman tanpa menyebabkan gangguan layanan.

Untuk menggunakan kunci sumber daya untuk mengautentikasi permintaan, kunci tersebut harus diteruskan sebagai Ocp-Apim-Subscription-Key header. Ini adalah contoh panggilan ke layanan Penerjemah Azure AI:

Ini adalah panggilan sampel ke layanan Penerjemah:

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

Mengautentikasi dengan kunci sumber daya AI Foundry

Anda dapat menggunakan kunci sumber daya AI Foundry untuk mengautentikasi permintaan untuk beberapa layanan Azure AI. Kredensial autentikasi tidak terkait dengan layanan tertentu. Lihat Harga layanan Azure AI untuk informasi tentang ketersediaan regional, fitur yang didukung, dan harga.

Kunci sumber daya disediakan di setiap permintaan sebagai Ocp-Apim-Subscription-Key header.

Wilayah yang didukung

Saat menggunakan kunci sumber daya AI Foundry untuk membuat permintaan ke api.cognitive.microsoft.com, Anda harus menyertakan wilayah dalam URL. Misalnya: westus.api.cognitive.microsoft.com.

Saat menggunakan kunci sumber daya AI Foundry dengan Azure AI Translator, Anda harus menentukan wilayah sumber daya dengan menggunakan tajuk Ocp-Apim-Subscription-Region.

Autentikasi sumber daya AI Foundry didukung di wilayah ini:

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

Sampel permintaan

Ini adalah contoh panggilan ke layanan Penerjemah Azure AI:

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

Mengautentikasi dengan token akses

Beberapa layanan Azure AI menerima, dan dalam beberapa kasus memerlukan token akses. Saat ini, layanan ini mendukung token akses:

API Terjemahan Teks
Layanan Ucapan: API Ucapan ke teks
Layanan Ucapan: API teks ke ucapan

Peringatan

Layanan yang mendukung token akses dapat berubah dari waktu ke waktu, jadi periksa referensi API untuk layanan sebelum menggunakan metode autentikasi ini.

Kunci sumber daya layanan AI Foundry dan AI dapat ditukar dengan token autentikasi. Token autentikasi berlaku selama 10 menit. Mereka disimpan dalam format JSON Web Token (JWT) dan dapat dikueri secara terprogram menggunakan pustaka JWT.

Token akses disertakan dalam permintaan sebagai header Authorization. Nilai token yang diberikan harus didahului oleh Bearer, misalnya: Bearer YOUR_AUTH_TOKEN.

Sampel permintaan

Gunakan URL ini untuk menukar kunci sumber daya dengan token akses: 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"

Wilayah ini mendukung pertukaran token untuk sumber daya AI Foundry:

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

Setelah mendapatkan token akses, Anda harus meneruskannya di setiap permintaan sebagai header Authorization. Ini adalah contoh panggilan ke layanan Penerjemah Azure AI:

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

Autentikasi dengan Microsoft Entra ID

Penting

Autentikasi Microsoft Entra selalu perlu digunakan bersama dengan nama subdomain kustom sumber daya Azure Anda. Titik akhir regional tidak mendukung autentikasi Microsoft Entra.

Di bagian sebelumnya, kami menunjukkan kepada Anda cara mengautentikasi menggunakan kunci API. Meski kunci ini memberikan jalur cepat dan mudah untuk memulai pengembangan, kunci tersebut kurang memadai dalam skenario yang memerlukan kontrol akses berbasis peran Azure (Azure RBAC). Mari kita lihat apa yang diperlukan untuk mengautentikasi dengan lebih aman menggunakan ID Microsoft Entra.

Di bagian berikut, Anda akan menggunakan lingkungan Azure Cloud Shell atau Azure CLI untuk membuat subdomain, menetapkan peran, dan mendapatkan token pembawa untuk memanggil layanan Azure AI. Jika Anda terjebak, tautan disediakan di setiap bagian dengan semua opsi yang tersedia untuk setiap perintah di Azure Cloud Shell/Azure CLI.

Penting

Jika organisasi Anda melakukan autentikasi melalui ID Microsoft Entra, Anda harus menonaktifkan autentikasi lokal (autentikasi dengan kunci) sehingga pengguna di organisasi harus selalu menggunakan ID Microsoft Entra.

Membuat sumber daya dengan subdomain kustom

Langkah pertama adalah membuat subdomain kustom. Jika Anda ingin menggunakan sumber daya AI Foundry yang sudah ada yang tidak memiliki nama subdomain kustom, ikuti instruksi di subdomain kustom layanan Azure AI untuk mengaktifkan subdomain kustom untuk sumber daya Anda.

Mulai dengan membuka Azure Cloud Shell. Kemudian pilih langganan:
```
Set-AzContext -SubscriptionName <SubscriptionName>
```

Selanjutnya, buat sumber daya AI Foundry dengan subdomain kustom. Nama subdomain harus unik secara global dan tidak dapat menyertakan karakter khusus, seperti: ".", "!", ",".

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

Jika berhasil, peserta harus menampilkan nama subdomain yang unik untuk sumber daya Anda.

Menetapkan peran ke perwakilan layanan

Sekarang setelah Anda memiliki subdomain khusus yang terkait dengan sumber daya Anda, Anda harus menetapkan peran untuk kepala layanan.

Catatan

Ingatlah bahwa penetapan peran Azure mungkin membutuhkan waktu hingga lima menit untuk disebarluaskan.

Pertama, mari kita daftarkan aplikasi Microsoft Entra.

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

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

Anda akan membutuhkan ApplicationId di langkah berikutnya.

Selanjutnya, Anda perlu membuat perwakilan layanan untuk aplikasi Microsoft Entra.
```
New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
```
Catatan

Jika Anda mendaftarkan aplikasi di portal Microsoft Azure, langkah ini selesai untuk Anda.
Langkah terakhir adalah menetapkan peran "Pengguna Azure Cognitive Services" ke perwakilan layanan (tercakup ke sumber daya). Dengan menetapkan peran, Anda memberikan akses pokok layanan ke sumber daya ini. Anda dapat memberikan akses pokok layanan yang sama ke beberapa sumber daya dalam langganan Anda.

Catatan

ObjectId dari perwakilan layanan digunakan, bukan ObjectId untuk aplikasi. ACCOUNT_ID akan menjadi Id sumber daya Azure dari sumber daya AI Foundry yang Anda buat. Anda dapat menemukan Id sumber daya Azure dari "properti" sumber daya di portal Microsoft Azure.
```
New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
```

Permintaan sampel

Dalam sampel ini, kata sandi digunakan untuk mengotentikasi perwakilan layanan. Token yang disediakan kemudian digunakan untuk memanggil Azure AI Vision API.

Dapatkan TenantId Anda:

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

Mendapatkan token:

$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

Catatan

Setiap kali Anda menggunakan kata sandi dalam skrip, opsi yang paling aman adalah menggunakan modul Manajemen Rahasia PowerShell dan berintegrasi dengan solusi seperti Azure Key Vault.

Memanggil Azure AI Vision API:

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

Atau, perwakilan layanan dapat diautentikasi dengan sertifikat. Selain perwakilan layanan, perwakilan pengguna juga didukung dengan memiliki izin yang didelegasikan melalui aplikasi Microsoft Entra lainnya. Dalam hal ini, alih-alih kata sandi atau sertifikat, pengguna akan diminta untuk autentikasi dua faktor saat memperoleh token.

Mengotorisasi akses ke identitas terkelola

Layanan Azure AI mendukung autentikasi Microsoft Entra dengan identitas terkelola untuk sumber daya Azure. Identitas terkelola untuk sumber daya Azure bisa mengotorisasi akses ke sumber daya AI Foundry menggunakan kredensial Microsoft Entra dari aplikasi yang berjalan di mesin virtual Azure, aplikasi fungsi, set skala mesin virtual, dan layanan lainnya. Dengan menggunakan identitas terkelola untuk sumber daya Azure bersama dengan autentikasi Microsoft Entra, Anda dapat menghindari penyimpanan kredensial dengan aplikasi Anda yang berjalan di cloud.

Mengaktifkan identitas terkelola pada Komputer Virtual (VM)

Sebelum Anda dapat menggunakan identitas terkelola untuk sumber daya Azure untuk mengotorisasi akses ke sumber daya AI Foundry dari VM, Anda harus mengaktifkan identitas terkelola untuk sumber daya Azure di VM. Untuk mempelajari cara mengaktifkan identitas terkelola untuk sumber daya Azure, lihat:

Untuk informasi selengkapnya tentang identitas terkelola, lihat Identitas terkelola untuk sumber daya Azure.

Menggunakan brankas kunci Azure untuk mengakses kredensial dengan aman

Anda dapat menggunakan Azure Key Vault untuk mengembangkan aplikasi Azure AI Foundry dengan aman. Key Vault memungkinkan Anda menyimpan kredensial autentikasi di cloud, dan mengurangi kemungkinan rahasia bocor secara tidak sengaja, karena Anda tidak akan menyimpan informasi keamanan di aplikasi Anda.

Autentikasi dilakukan melalui ID Microsoft Entra. Otorisasi dapat dilakukan melalui kontrol akses berbasis peran Azure (Azure RBAC) atau kebijakan akses Key Vault. RBAC Azure dapat digunakan untuk pengelolaan brankas dan mengakses data yang disimpan dalam brankas, sementara kebijakan akses brankas kunci hanya dapat digunakan ketika mencoba mengakses data yang disimpan di brankas.

Bagikan melalui

Mengautentikasi permintaan ke layanan Azure AI

Prasyarat

Header autentikasi

Mengautentikasi dengan kunci sumber daya layanan tunggal

Mengautentikasi dengan kunci sumber daya AI Foundry

Wilayah yang didukung

Sampel permintaan

Mengautentikasi dengan token akses

Sampel permintaan

Autentikasi dengan Microsoft Entra ID

Membuat sumber daya dengan subdomain kustom

Menetapkan peran ke perwakilan layanan

Permintaan sampel

Mengotorisasi akses ke identitas terkelola

Mengaktifkan identitas terkelola pada Komputer Virtual (VM)

Menggunakan brankas kunci Azure untuk mengakses kredensial dengan aman

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: