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