Azure AI 搜尋 REST API 參考
Azure AI 搜尋（先前稱為 Azure 認知搜尋），是完全受控的雲端搜尋服務，可提供使用者擁有內容的資訊擷取。
數據平面 REST API 用於編製索引和查詢工作流程，並記載於本節中。
服務管理的控制平面作業涵蓋在個別 管理 REST API中。
版本設定的 API 檔
REST API 檔現在已建立版本。 當您開啟 API 參考頁面時，版本選取器會出現在目錄上方。 請確定 API 參考來自數據平面
重要概念
Azure AI 搜尋具有 搜尋服務、索引、檔、索引器、數據源、技能集的概念，以及 同義字對應。
- 搜尋服務會將索引、索引器、數據源、技能集和同義字對應裝載為最上層物件。
- 搜尋索引提供搜尋檔的永續性儲存。 搜尋檔是您的數據，以字段集合的形式表達，從外部來源載入並推送至索引，使其可供搜尋。
- 搜尋索引器會新增自動化、以原生格式讀取數據，並將其串行化為 JSON。
- 索引器具有數據源，並指向索引。
- 索引器也可能有一個技能集，可將 AI 擴充 和 整合向量化 新增至索引管線。 技能集一律會附加至索引器。 它們會叫用機器學習來擷取或區塊文字、向量化內容、推斷功能，或將結構新增至內容，以改善搜尋服務的索引編製。
您完全可以在搜尋服務上建立下列物件：
| 物件 | 描述 |
|---|---|
| 數據源 | 索引器用來擷取和重新整理索引文件的數據源連接。 資料來源具有 type。 您可以使用 Azure 或合作夥伴連接器Microsoft提供的連線。 如需完整清單，請參閱 數據源資源庫。 |
| 檔 | 就概念上講，檔是索引中的實體。 將此概念對應至更熟悉的資料庫對等專案：搜尋索引等同於數據表，而檔大致相當於數據表中的數據列。 檔只存在於索引中，而且只會透過以索引之檔集合 （/docs） 為目標的查詢來擷取。 在集合上執行的所有作業，例如上傳、合併、刪除或查詢檔都會發生在單一索引的內容中，因此 URL 格式檔案作業一律會包含指定索引名稱的 /indexes/[index name]/docs。 |
| 指標 | 索引會儲存在搜尋服務上，並填入已編製索引並標記的 JSON 檔，以便擷取資訊。 索引的 fields 集合會定義搜尋文件的結構。 欄位具有決定使用方式的名稱、數據類型和屬性。 例如，searchable 字段用於全文搜索，因此在編製索引期間標記化。 索引也會定義其他建構，例如相關性微調、建議工具、語意設定和自定義分析器的評分配置檔。 |
| 索引 | 索引器提供索引自動化。 索引器會連線到數據源、讀取數據，並將它傳遞給搜尋引擎，以便編製索引至目標搜尋索引。 索引器會使用數據源中的連接資訊從外部來源讀取，並將傳入數據串行化為 JSON 搜尋檔。 除了數據源之外，索引器也需要索引。 索引會指定搜尋檔的欄位和屬性。 |
| 技能集 | 技能集會將外部處理步驟新增至索引器執行，並用於套用 AI 或深度學習模型來分析或轉換內容，以改善索引中的可搜尋性。 技能集的內容是一或多個 技能，它可以 內建技能 由Microsoft、自定義技能或兩者的組合所建立。 影像分析的內建技能存在，包括 OCR 和自然語言處理。 內建技能的其他範例包括實體辨識、關鍵片語擷取、將文字區塊化為邏輯頁面等等。 技能集是高階獨立物件，其存在於相當於索引、索引器和數據源的層級上，但它只能在索引器處理中運作。 身為高階物件，您可以設計技能集一次，然後在多個索引器中參考。 |
| 同義字對應 | 同義字對應是包含使用者定義同義字的服務層級物件。 此物件與搜尋索引獨立維護。 上傳之後，您可以將任何可搜尋的欄位指向同義字對應（每個字段一個）。 |
許可權和訪問控制
您可以透過Microsoft Entra識別碼，使用密鑰型驗證或角色型。
金鑰型驗證 依賴為搜尋服務產生的 API 金鑰。 讓有效的金鑰會根據每個要求在傳送要求與處理它的服務之間建立信任。 您可以使用 系統管理 API 金鑰 進行讀寫作業，或 查詢 API 金鑰，以讀取搜尋索引的檔集合。
Microsoft Entra ID 驗證和角色型訪問控制，您必須在具有安全性主體和角色指派Microsoft Entra ID 中建立租使用者。 下列角色的成員具有數據平面存取權。 如果內建角色不足，您可以建立自定義角色。
角色 訪問 搜尋服務參與者 存取物件，但無法存取索引內容。 此角色會建立搜尋索引和其他最上層物件，但無法查詢搜尋索引或新增、移除或更新搜尋索引中的檔。 此角色適用於建立、更新和刪除物件定義的開發人員。 它也適用於需要管理對象的系統管理員，但無法檢視或存取對象數據。 搜尋數據索引參與者 索引內容的讀寫存取權。 此角色適用於需要匯入、重新整理或查詢索引檔集合的開發人員或索引擁有者。 搜尋數據索引讀取器 讀取索引內容的存取權。 這個角色適用於執行查詢的應用程式和使用者。
在連線上使用角色時，用戶端應用程式會在授權標頭中呈現持有人令牌。 請參閱 使用 Microsoft Entra ID 授權搜尋應用程式的存取權，以取得設定此設定的說明。
您可以停用金鑰型驗證或角色型驗證。 如果您停用角色型驗證，它只會套用至數據平面作業。 控制平面作業，例如服務管理，一律使用角色型驗證。 如需詳細資訊，請參閱 azure AI 搜尋
呼叫 API
本節記載的 API 可讓您存取搜尋數據的作業，例如索引建立和母體擴展、檔上傳和查詢。 呼叫 API 時，請記住下列幾點：
要求必須透過 HTTPS 發出（在預設埠 443 上）。
要求 URI 必須包含 api-version。 值必須設定為支援的版本，格式如下範例所示：
GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01要求標頭 必須包含已驗證連線的 api 金鑰 或持有人令牌。 您可以選擇性地設定 Accept HTTP 標頭。 如果未設定內容類型標頭，則預設會假設為
application/json。