針對 Azure AI 搜尋中分享私人鏈接的問題進行疑難解答

Note

Azure AI 搜尋服務 可透過 Azure 入口網站、REST API 及 Azure SDK 取得。 它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

共用私人連結可讓 Azure AI 搜尋服務在存取虛擬網路的客戶資源時，透過私人端點進行安全的輸出連線。 本文可協助您解決可能發生的錯誤。

建立共用私人連結是搜尋服務的控制平面作業。 您可以使用 Azure 入口網站或管理 REST API 來建立共用私人連結。 在配置期間，要求的狀態為 Updating。 工作成功完成之後，狀態為 Succeeded。 系統會建立資源的私人端點，以及任何 DNS 區域與對應。 此端點會由您的搜尋服務執行個體獨佔使用，並透過 Azure AI 搜尋服務來管理。

建立共用私人連結資源所需的步驟

以下是在建立階段期間發生的常見錯誤。

要求驗證失敗

  • 不支援的 SKU：基本層及更高層級才可支援共用私人連結。 如為包含技能集的索引子，最低層級為標準 1 (S1)。 如需詳細資訊，請參閱 共用私人鏈接資源限制。

  • 名稱無效：共用私人連結的命名規則如下：

    • 長度必須介於 1 到 60 個字元
    • 英數字元
    • 名稱可包含底線 _、句號 . 和連字號 -，但這些符號不得為名稱中的第一個字元

  • 無效的群組標識碼：群組標識符區分大小寫，而且必須是下列其中一個值。

    Azure 資源 群組識別碼 第一個可用的 API 版本
    Azure 儲存體 - Blob (或) ADLS Gen 2 blob 2020-08-01
    Azure 儲存體 - 資料表 table 2020-08-01
    Azure Cosmos DB for NoSQL Sql 2020-08-01
    Azure SQL Database sqlServer 2020-08-01
    適用於 MySQL 的 Azure 資料庫 (預覽) mysqlServer 2020-08-01-Preview
    Azure Key Vault vault 2020-08-01
    Azure Functions (預覽) sites 2020-08-01-Preview

    標示「(預覽)」的資源，必須使用管理 REST API 的預覽版來建立。

  • privateLinkResourceId 類型驗證：Azure AI 搜尋服務類似於 groupId，會驗證 privateLinkResourceId 所指定的資源類型「正確」。 以下為有效的資源類型：

    Azure 資源 資源類型 第一個可用的 API 版本
    Azure 儲存體 Microsoft.Storage/storageAccounts 2020-08-01
    Azure Cosmos DB Microsoft.DocumentDb/databaseAccounts 2020-08-01
    Azure SQL Database Microsoft.Sql/servers 2020-08-01
    Azure Key Vault Microsoft.KeyVault/vaults 2020-08-01
    適用於 MySQL 的 Azure 資料庫 (預覽) Microsoft.DBforMySQL/servers 2020-08-01-Preview
    Azure Functions (預覽) Microsoft.Web/sites 2020-08-01-Preview
    Azure SQL 受控執行個體 (預覽) Microsoft.Sql/managedInstance 2020-08-01-Preview

    此外，指定的 groupId 必須對指定的資源類型有效。 例如， groupId “blob” 對 類型 Microsoft.Storage/storageAccounts有效，無法與任何其他資源類型搭配使用。 針對特定搜尋管理 API 版本，客戶可以使用groupId 找到支援的 和資源類型詳細資訊。

  • 配額限制強制執行：搜尋服務對於可建立的共用私人連結資源數量及使用中的各類目標資源類型數量 (以 groupId 為依據) 會加諸配額限制。 如需詳細資訊，請參閱 共用私人鏈接資源限制。

部署失敗

搜尋服務會發起建立共用私人連結的要求，但 Azure Resource Manager 則執行實際工作。 您可以在 Azure 入口網站或使用查詢檢查部署的狀態，並解決可能發生的任何錯誤。

Azure Resource Manager 部署失敗的共用的私人連結資源會顯示在 列表 和 取得 API 呼叫中，但其「布建狀態」為 Failed。 確定 Azure Resource Manager 部署失敗的原因之後，請刪除 Failed 資源，並在套用下表的適當解決方案之後重新建立資源。

部署失敗原因 描述 解決方案
「LinkedAuthorizationFailed」 錯誤訊息指出用戶端有權在搜尋服務建立共用私人連結，但無權在連結範圍內執行動作 'privateEndpointConnectionApproval/action'。 重新檢查要求中的私人鏈接識別碼，以確定 URI 中沒有任何錯誤或遺漏。 如果 Azure AI 搜尋和 Azure PaaS 資源位於不同的訂用帳戶中，而且您使用 REST 或命令列介面，請確保 作用中的 Azure 帳戶是 Azure PaaS 資源的帳戶。 如為 REST 用戶端，請確保您沒有使用過期的持有人權杖，且權杖對作用中的訂用帳戶有效。
網路資源提供者未在目標資源的訂用帳戶註冊 系統會透過 Microsoft.Network 資源提供者 (RP) 為目標資源 (儲存體帳戶、Azure Cosmos DB、Azure SQL) 建立私人端點 (以及相關聯的 DNS 對應)。 如果主控目標資源的訂用帳戶 (「目標訂用帳戶」) 未向 Microsoft.Network RP 註冊，則 Azure Resource Manager 部署可能會失敗。 您必須在其目標訂用帳戶註冊此 RP。 您可以使用 Azure 入口網站、PowerShell 或 CLI 來註冊資源提供者。
目標資源的 groupId 無效 建立 Azure Cosmos DB 帳戶時，您可以指定資料庫帳戶的 API 類型。 雖然 Azure Cosmos DB 提供數種不同 API 類型，但 Azure AI 搜尋服務僅支援以「Sql」當作共用私人連結資源的 groupId。 為 privateLinkResourceId 建立類型為「SQL」的共用私人連結時，如指向非 SQL 的資料庫帳戶的，由於 groupId 不相符，Azure Resource Manager 部署會失敗。 Azure Cosmos DB 帳戶的 Azure 資源 ID 不足以判斷使用中的 API 類型。 Azure AI 搜尋會嘗試建立私人端點，Azure Cosmos DB 接著會拒絕此端點。 您必須確保指定 Azure Cosmos DB 資源的 privateLinkResourceId 是「Sql」API 類型的資料庫帳戶
找不到目標資源 只有在 Azure Resource Manager 部署開始期間，系統才會檢查 privateLinkResourceId 的指定目標資源是否存在。 如果目標資源已無法使用，則部署會失敗。 您必須確保指定的訂用帳戶和資源群組中存在目標資源，且不會移動或刪除。
暫時性/其他錯誤 如果有基礎結構中斷或其他非預期的原因，Azure Resource Manager 部署可能會失敗。 這種情況理應很少見，且通常會指出是暫時性狀態。 請稍後再重新嘗試建立此資源。 如果問題持續發生，請聯絡 Azure 支援。

核准備援私人端點時發生問題

私人端點會按照共用私人連結建立的要求所指定，在目標 Azure 資源中建立。 這是非同步 Azure Resource Manager 部署作業的其中一個最終步驟，但 Azure AI 搜尋服務在其網路組態設定過程中，必須連結私人端點的私人 IP 位址。 完成此連結之後， provisioningState 共用私人連結資源的 會進入終端機成功狀態 Succeeded。 在狀態轉換至 Succeeded之後，客戶應該只核准或拒絕（或一般修改備份私人端點的組態）。 在此之前以任何方式修改私人端點，都可能會導致部署作業不完整，且可能導致共用私人連結資源以 Failed 狀態結束 (立即結束或在幾個小時內結束)。

搜尋服務網路連線變更停滯在「正在更新」狀態

搜尋服務的 [公用網路存取] 為 [停用] 時，系統會使用共用私人連結和私人端點。 一般而言，在接受要求后幾分鐘內，變更網路連線應該會成功。 在某些情況下，Azure AI 搜尋可能需要數小時才能完成連線變更作業。

螢幕擷取畫面為將公用網路存取變更為停用。

如果您發現連線變更作業需花費大量時間，請等候幾小時。 連線變更作業包括更新作業，例如更新 DNS 記錄，這可能需要比預期更長的時間。

如果 公用網路存取 已變更，現有的共用私人連結和私人端點可能無法正常運作。 如果現有的共用私人連結和私人端點在連線變更作業期間停止運作，請等候幾小時讓作業完成。 如果之後仍無法運作，請嘗試刪除並重新建立。

一般而言，共用私人鏈接資源在接受要求后的幾分鐘內應該會進入終端機狀態（Succeeded 或 Failed）。

少數情況下，Azure AI 搜尋服務可能無法正確將共用私人連結資源的狀態標示為終端狀態 (Succeeded 或 Failed)。 這通常是因未預期的失敗所造成。 如果共用私人鏈接資源處於非決定性狀態超過幾個小時，就會自動轉換為 Failed 狀態。

如果共用私人連結資源未轉換為終端狀態，請等候數小時，確保它變成 Failed，再刪除並重新建立。 除了等待之外，您也可以嘗試建立另一個不同名稱的共用私人連結資源 (所有其他參數都維持不變)。

您可以使用建立或更新 API 來更新現有的共用私人連結資源。 搜尋只允許縮小共用私人連結資源的更新範圍 - 請求訊息僅能透過此 API 修改。

  • 您無法更新現有共用私人連結資源的任何「核心」屬性 (例如 privateLinkResourceId 或 groupId)，且這項設定永遠不會改變。 如有請求訊息以外的任何其他屬性需要變更，建議客戶刪除並重新建立共用私人連結資源。

  • 只有佈建狀態到達 Succeeded 時，您才可以更新共用私人連結資源的請求訊息。

客戶可以透過刪除 API 刪除現有的共用私人連結資源。 與建立 (或更新) 程序相同的是，它也是包含四個步驟的非同步作業：

  1. 您請求搜尋服務刪除共用私人連結資源。

  2. 搜尋服務會驗證資源是否存在，且是可刪除的有效狀態。 如果是，它會發起 Azure Resource Manager 刪除作業來移除資源。

  3. 搜尋完成作業的查詢 (通常需要幾分鐘的時間)。 此時，共享的私人鏈結資源會有 佈署狀態 Deleting。

  4. 作業完成之後，備援私人端點和任何關聯 DNS 對應就會移除。 資源不會顯示為 List 作業的一部分，且嘗試對此資源執行 Get 作業將會導致 404 Not Found 錯誤。

刪除共用私人連結資源所需的步驟

以下是刪除階段期間發生的常見錯誤。

失敗類型 描述 解決方案
資源處於非結束狀態 非終端狀態 (Succeeded 或 Failed) 的共用私人連結資源無法刪除。 共用私人連結資源可能停滯在非中斷狀態長達 8 小時 (罕見情況)。 等候資源達到終端機狀態，然後重試刪除要求。
刪除作業失敗，並出現錯誤「衝突」 刪除共用私人連結資源的 Azure Resource Manager 作業會先連繫 privateLinkResourceId (「目標 RP」) 指定的目標資源的資源提供者，才能移除私人端點和 DNS 對應。 客戶可以利用 Azure 資源鎖定來防止其資源發生任何變更。 Azure Resource Manager 連繫目標 RP 後，會要求目標 RP 修改目標資源的狀態 (以便從其中繼資料移除私人端點的相關詳細資訊)。 如果目標資源 (或其資源群組/訂用帳戶) 有設定鎖定，Azure Resource Manager 作業會失敗，並出現「衝突」(及相關詳細資訊)。 共用私人連結資源不會遭到刪除。 客戶應先移除目標資源的鎖定，再重試刪除作業。 注意：如果客戶嘗試刪除搜尋服務時，共用私人連結資源指向「鎖定」的目標資源，也可能發生此問題
刪除作業失敗 罕見情況下，非同步 Azure Resource Manager 的刪除作業可能會失敗。 當這項作業失敗時，查詢異步作的狀態會顯示錯誤訊息和適當的詳細數據。 請稍後再重試作業，如果問題持續發生，請連絡 Azure 支援。
資源停滯在「正在刪除」狀態 罕見情況下，共用私人連結資源可能會停滯於「正在刪除」狀態長達 8 小時，這可能是因為搜尋 RP 發生重大失敗所致。 請等候 8 小時，之後資源會轉換至 Failed 狀態，然後再重新發出請求。

後續步驟

深入了解共用私人連結資源，以及如何將它用於受保護內容的安全存取。

  • Last updated on