Autentikasi dengan Microsoft Web IQ

Ada dua cara untuk mengautentikasi dan mendapatkan akses ke API IQ Web Microsoft. Gunakan kunci API untuk memulai paling cepat, dan Microsoft Entra ID untuk beban kerja produksi.

Kunci API

Buat kunci API di portal Microsoft Web IQ untuk mengautentikasi dengan API Web IQ Microsoft. Sertakan di header x-apikey pada setiap permintaan:

x-apikey: <YOUR_API_KEY>

Warning

Kunci API memberikan akses penuh ke akun Anda. Simpan di secret manager, bukan di kode sisi klien atau source control.

Microsoft Entra ID

Gunakan Microsoft Entra ID OAuth 2.0 Client Credentials (token khusus aplikasi) untuk mengautentikasi dengan API Microsoft Web IQ.

Note

Microsoft Entra ID adalah platform identitas. Pendaftaran aplikasi memiliki ID Aplikasi (klien), yang mengidentifikasi aplikasi di tenant Anda dan merupakan nilai yang Anda ikat ke akun Web IQ Anda. Saat runtime, aplikasi Anda menukar kredensialnya dengan token akses Microsoft Entra untuk disertakan dengan setiap permintaan API.

Prerequisites

  1. Siapkan tenant: Untuk mendaftarkan aplikasi Anda, tenant Azure diperlukan. Langganan Azure tidak diperlukan, tetapi jika organisasi Anda sudah memiliki satu atau beberapa langganan Azure atau organisasi Microsoft 365, maka Anda sudah memiliki tenant Azure. Jika tidak, sediakan tenant baru.

  2. Buat pendaftaran aplikasi: Pendaftaran aplikasi membangun hubungan kepercayaan antara aplikasi Anda dan platform identitas Microsoft, memungkinkan aplikasi Anda untuk mengautentikasi dan mengakses sumber daya dengan aman.

    Saat Anda mendaftarkan aplikasi, ID klien, ID objek, dan ID direktori dibuat. Untuk membuat kredensial untuk pendaftaran aplikasi Anda, lihat Mendaftarkan aplikasi dengan Microsoft Identity Platform.

langkah-langkah penyiapan Entra ID

  1. Pendaftaran aplikasi - Gunakan pendaftaran aplikasi Microsoft Entra ID yang ada atau buat pendaftaran aplikasi. Catat ID Aplikasi (klien). Di portal Azure, temukan di Microsoft Entra ID>Pendaftaran aplikasi>aplikasi Anda>.

  2. Tautkan pendaftaran aplikasi Anda - Buka Manajemen Profil, pilih tab ID Aplikasi (Klien), lalu pilih Tautkan ID Aplikasi (Klien). Masukkan ID aplikasi (klien) Anda. Pembaruan profil dapat memakan waktu hingga satu menit untuk disinkronkan.

    Note

    Jika tab ID Aplikasi (Klien) tidak tersedia, autentikasi Microsoft Entra ID mungkin tidak diaktifkan untuk uji coba Anda. Hubungi perwakilan Microsoft Anda untuk meminta akses khusus.

  3. Dapatkan token - Gunakan grant client credentials dengan Pustaka Autentikasi Microsoft (MSAL) pilihan Anda:

    • Otoritas: https://login.microsoftonline.com/{your-tenant-id}
    • Ruang lingkup: https://api.microsoft.ai/.default

Kemudian teruskan token akses pada setiap permintaan Web IQ:

Authorization: Bearer <access-token>

Memanggil lebih dari satu AppID

Satu ID Aplikasi (klien) dapat terikat ke lebih dari satu Web IQ AppID, misalnya satu AppID per sumber daya Web IQ atau per beban kerja. Jika ya, tambahkan parameter kueri APPID ke setiap permintaan untuk memilih AppID mana yang digunakan panggilan. Batas rate limit dihitung terhadap AppID tersebut.

POST https://api.microsoft.ai/v3/search/web?APPID=<your-web-iq-appid>
Authorization: Bearer <access-token>
Content-Type: application/json

APPID mengambil Web IQ AppID Anda, bukan ID Aplikasi (klien) Anda. Kontak Microsoft Anda memberikan Web IQ AppIDs Anda.

ID Aplikasi (klien) Anda terikat ke APPID atas permintaan Result
Satu AppID Tidak ada, atau AppID tersebut Permintaan berhasil
Satu AppID AppID yang berbeda HTTP 403 AuthUnauthorizedAppId
Beberapa AppID Hilang atau kosong HTTP 400 AuthAppIdSelectionRequired
Beberapa AppID Salah satu AppID Anda yang ditautkan Permintaan berhasil
Beberapa AppID AppID lain apa pun HTTP 403 AuthUnauthorizedAppId
Tidak Ada AppID Apa saja HTTP 401 AuthUnauthorizedEntryId

Warning

Kunci API tidak menerima APPID. Setiap kunci API milik satu AppID. Permintaan yang diautentikasi dengan kunci yang menyertakan parameter APPID, bahkan jika kosong, mengembalikan HTTP 401 AuthUnauthorizedEntryId.

Tajuk permintaan

Header Value Description
x-apikey atau Authorization <your-api-key> atau Bearer <access-token> Kunci API Anda atau token akses Microsoft Entra ID untuk autentikasi
Content-Type application/json Format isi permintaan

Langkah berikutnya

Dukungan dan umpan balik

Kirim masalah teknis atau umpan balik ke Web IQ Support.

  • Terakhir diperbarui pada