共用方式為

針對 Azure AI 搜尋服務中共用私人連結問題進行疑難排解

  • 發行項

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

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

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

以下列出了在建立階段期間發生的一些常見錯誤。

要求驗證失敗

  • 不支援的 SKU：基本層和以上版本支援共用私人連結。 針對具備技能集的索引子，最低分層是標準 2 (S2)。

  • 不正確的名稱：共用私人連結的命名規則如下：

    • 長度必須介於 1 到 60 個字元之間
    • 英數字元
    • 只要不是名稱中的第一個字元，名稱就可以包含底線 _、句號 . 和連字號 -

  • 不正確的群組識別碼：群組識別碼區分大小寫，且必須是下表中的其中一個值：

    Azure 資源 群組識別碼 第一個可用的 API 版本
    Azure 儲存體 - Blob (或) ADLS Gen 2 blob 2020-08-01
    Azure 儲存體 - 資料表 table 2020-08-01
    適用於 NoSQL 的 Azure Cosmos DB 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 類型驗證：類似於 groupId，Azure AI 搜尋服務會驗證 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 版本，客戶可以使用列出支援的 API 來找出支援的 groupId 和資源類型詳細資料。

  • 配額限制強制執行：搜尋服務會將配額加諸在可建立的共用私人連結資源數目，以及所使用的各種目標資源類型數目上 (根據 groupId)。 這些資訊記載於 Azure AI 搜尋服務限制頁面的 [共用私人連結資源限制] 區段中。

部署失敗

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

Azure Resource Manager 部署失敗的共用私人連結資源會在 List 和 Get 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」類型的共用私人連結時，Azure Resource Manager 部署將會因為 groupId 不相符而失敗。 Azure Cosmos DB 帳戶的 Azure 資源識別碼不足以判斷所使用的 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，然後才能將其刪除並重新建立。 或者，您可以嘗試建立另一個具有不同名稱的共用私人連結資源 (維持所有其他參數相同)，而不是等待。

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

  • 您無法更新現有共用私人連結資源 (例如 privateLinkResourceId 或 groupId) 的任何「核心」屬性，而且一律不受支援。 如果需要變更要求訊息以外的任何其他屬性，我們建議客戶刪除並重新建立共用私人連結資源。

  • 只有在共用私人連結資源已達到 Succeeded 的佈建狀態，才能嘗試更新其要求訊息。

客戶可以透過 Delete API 刪除現有的共用私人連結資源。 與建立 (或更新) 的流程類似，這也是具有四個步驟的非同步作業：

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

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

  3. 搜尋作業完成的查詢 (通常需要幾分鐘的時間)。 此時，共用私人連結資源會有「正在刪除」的佈建狀態。

  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 狀態，然後重新發出要求。

下一步

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