透過共用私人連結進行輸出連線

發行項
12/19/2024

本文說明如何設定從 Azure AI 搜尋到在 Azure 虛擬網路內執行的 Azure 資源的私人輸出呼叫。

設定私人連線以允許搜尋服務連線至虛擬網路 IP 位址，而非對網際網路開放的連接埠。針對此連線建立的物件稱為「共用私人連結」。在連線上，搜尋服務會在內部使用共用的私人連結來連線到網路界限內的 Azure 資源。

共用私人連結是依使用量收費的進階功能。設定共用私人連結，私人端點的費用會附加至您的 Azure 發票。當您使用共用私人連結時，輸入和輸出存取的資料傳輸速率也會收費。如需詳細資料，請參閱 Azure Private Link 定價。

注意

如果您要設定與 SQL 受控執行個體的私人索引子連線，請改為參閱本文，以了解適用於該資源類型的特定步驟。

使用共用私人連結的時機

Azure AI 搜尋會在下列案例中對其他 Azure 資源進行輸出呼叫：

Azure OpenAI、Azure AI Vision 或 Azure AI Foundry 模型目錄的索引器或查詢連線以進行向量化
與受支援資料來源的索引子連線
與 Azure 儲存體的索引子 (技能集) 連線，用於快取豐富內容、偵錯工作階段狀態或寫入知識存放區
索引器（技能集）連線至 Azure AI 服務以供計費之用
對 Azure Key Vault 的加密金鑰要求
對 Azure Functions 或類似資源的技能要求

共用私人連結僅適用於 Azure 對 Azure 連線。如果您要連線到 OpenAI 或其他外部模型，則連線必須透過公用網際網路進行。

共用私人連結適用於透過 Azure 資源或在 Azure 虛擬網路中執行的用戶端的私人端點存取的作業和資料。

共用私人連結的特點如下：

使用 Azure AI 搜尋服務工具、API 或 SDK 建立
由 Azure 資源擁有者核准
由 Azure AI 搜尋服務在針對特定 Azure 資源的私人連線內部使用

只有您的搜尋服務可使用其建立的私人連結，且每個資源和子資源組合只能在您的服務上建立一個共用私人連結。

設定私人鏈接之後，每當搜尋服務連線到該資源時，就會自動使用它。您不需要修改連接字串或改變您用來發出要求的客戶端，不過用於連線的裝置必須使用 Azure 資源防火牆中的授權 IP 進行連線。

搭配使用 Azure Private Link 和 Azure AI 搜尋服務的狀況有兩種。

案例一：當連至 Azure 的輸出 （索引器）連線需要私人連線時，建立共用的私人連結。
場景二：設定搜尋服務以進行來自虛擬網路中執行的用戶端的私人輸入連線。

本文介紹了場景一。

雖然這兩個狀況都依賴於 Azure Private Link，但兩者互不影響。您可以建立共用私人連結，而不需要針對私人端點設定您自己的搜尋服務。

限制

當您根據自身案例評估共用私人連結時，請記住以下限制。

共用私人連結中使用的數種資源類型處於預覽狀態。如果您要連線到預覽資源（適用於 MySQL 的 Azure 資料庫或 Azure SQL 受控執行個體），請使用管理 REST API 的預覽版本來建立共用的私人連結。這些版本包括 2020-08-01-preview、2021-04-01-preview、2024-03-01-preview 和 2024-06-01-preview。我們建議使用最新的預覽版 API。
索引器執行必須使用搜尋服務專屬的私人執行環境。多租用戶內容處理環境不支援私人端點連線。本文已涵蓋此需求的組態設定。
檢閱每個層級的共用私人鏈接資源限制。

必要條件

支援的 Azure 資源，設定為在虛擬網路中執行。

依工作負載，具有階層和區域需求的 Azure AI 搜尋服務：

工作負載	階層需求	區域需求	服務建立需求
沒有技能集的索引器	基本和更新版本	無	無
內嵌技能的技能集（整合向量化）	基本和更新版本	高容量區域	2024 年 4 月 3 日之後
使用其他內建或自定義技能的技能集	標準 2 （S2）和更新版本	無	2024 年 4 月 3 日之後

Azure AI 搜尋和 Azure 資源的許可權：

資源	權限
Azure AI 搜尋服務	`Microsoft.Search/searchServices/sharedPrivateLinkResources/write` `Microsoft.Search/searchServices/sharedPrivateLinkResources/read` `Microsoft.Search/searchServices/sharedPrivateLinkResources/operationStatuses/read`
其他 Azure 資源	核准私人端點連線的許可權。例如，在 Azure 儲存體上，您需要 `Microsoft.Storage/storageAccounts/privateEndpointConnectionsApproval/action`。

支援的資源類型

您可以建立下列資源的共用私人連結。

資源類型	子資源 (或群組識別碼)
Microsoft.Storage/storageAccounts ¹	`blob`、、 `table`、 `dfsfile`
Microsoft.DocumentDB/databaseAccounts ²	`Sql`
Microsoft.Sql/servers ³	`sqlServer`
Microsoft.KeyVault/vaults	`vault`
Microsoft.DBforMySQL/servers (預覽)	`mysqlServer`
Microsoft.Web/sites ⁴	`sites`
Microsoft.Sql/managedInstances (預覽) ⁵	`managedInstance`
Microsoft.CognitiveServices/accounts ⁶ ⁷	`openai_account`
Microsoft.CognitiveServices/accounts ⁸	`cognitiveservices_account`

¹ 如果 Azure 儲存體和 Azure AI 搜尋服務位於相同區域，則會透過 Microsoft 骨幹網路建立與儲存體的連線，因此，這個組態下不需要共用私人連結。不過，如果您已經為 Azure 儲存體設定私人端點，則應該一併設定共用的私人連結，否則儲存體端會拒絕連線。此外，如果您在搜尋的各種案例中使用多個儲存體格式，請務必為每個子資源建立個別的共用私人連結。

² 與 Azure Cosmos DB for NoSQL 的索引子連線會使用 Microsoft.DocumentDB/databaseAccounts 資源類型。提供者名稱和群組識別碼區分大小寫。

³ Microsoft.Sql/servers 資源類型用於連線到 Azure SQL 資料庫。目前不支援 Azure Synapse SQL 的共用私人連結。

⁴ App Service 和 Azure Functions 會使用 Microsoft.Web/sites 資源類型。以 Azure AI 搜尋服務而言，較可能使用 Azure Function。 Azure Function 通常用於裝載自訂技能的邏輯。 Azure Function 具有「取用」、「進階」和「專用」App Service 主控方案。目前不支援 App Service 環境 (ASE)、Azure Kubernetes Service (AKS) 和 APIM。

⁵ 如需指示，請參閱建立 SQL 受控執行個體的共用私人連結。

⁶ 實作整合向量化時，資源Microsoft.CognitiveServices/accounts類型可用於 Azure OpenAI 內嵌模型的向量化工具和索引器連線。自 2024 年 11 月 19 日起，現在支援將模型內嵌在 Azure AI Foundry 模型目錄中或 Azure AI 視覺多模式 API 的共用私人連結。

⁷ 只有公用雲端才支援 Azure OpenAI 的共用私人連結。其他雲端供應專案，例如 Microsoft Azure Government 不支援群組標識符的共用私人連結 openai_account 。

⁸ 現在支持共用私人連結（截至 2024 年 11 月），以連線到 Azure AI 多服務帳戶。 Azure AI 搜尋會連線到 Azure AI 多重服務以進行計費。這些連線現在可以透過共用私人連結私用。只有在技能集定義中設定受控識別（無密鑰組態）時，才支持共用私人連結。

1. 建立共用的私人連結

使用 Azure 入口網站、管理 REST API、Azure CLI 或 Azure PowerShell 來建立共用的私人連結。

以下提供一些祕訣：

為私人連結提供有意義的名稱。在 Azure PaaS 資源中，共用的私人連結會與其他私人端點一起顯示。「用於搜尋的共用私人連結」這類名稱可協助您識別其功能。

當您完成本節中的步驟時，將會擁有一個以擱置狀態佈建的共用私人連結。 建立連結需要幾分鐘的時間。建立之後，資源擁有者必須先核准要求，連結才能運作。

登入 Azure 入口網站，然後尋找您的搜尋服務。
在左側瀏覽窗格的[設定] 底下選取 [網路]。
在 [共用私人存取] 頁面籤上選取 [+ 新增共用私人存取]。
選取 [連線至我目錄中的 Azure 資源] 或 [依資源識別碼連線至 Azure 資源]。
如果您選取第一個選項（建議），Azure 入口網站可協助您挑選適當的 Azure 資源，並填入其他屬性，例如資源的群組標識碼和資源類型。
如果您選取第二個選項，請手動輸入 Azure 資源識別碼，並從本文開頭的清單中選擇適當的群組識別碼。
確認佈建狀態為「正在更新」。
成功建立資源之後，資源佈建狀態會變更為「成功」。

注意

處於預覽狀態的群組識別碼需要預覽 API 版本。下列資源類型處於預覽狀態：managedInstance、mySqlServer、sites。

雖然 Azure 入口網站、Azure PowerShell 或 Azure CLI 等工具有帳戶登入的內建機制，但 REST 用戶端必須提供可讓您要求通過的持有人權杖。

本節會使用 Azure CLI 步驟來取得持有人權杖，因為此方法簡單且快速。如需更長期的方法，請參閱使用 REST 進行管理。

開啟命令列並執行 az login 進行 Azure 登入。
顯示作用中的帳戶和訂用帳戶。確認此訂用帳戶是擁有您建立共用私人連結所使用 Azure PaaS 資源的相同帳戶。
```
az account show
```
如果訂用帳戶不是正確的訂用帳戶，請進行變更：
```
az account set --subscription {{Azure PaaS subscription ID}}
```
建立持有人權杖，然後複製整個權杖 (引號之間的所有內容)。
```
az account get-access-token
```

切換至 REST 用戶端，並設定 GET 共用私人連結資源。檢閱現有的共用私人連結以確保您沒有重複連結。每個資源和子資源組合只能有一個共用私人連結。

@subscriptionId = PASTE-HERE
@rg-name = PASTE-HERE
@service-name = PASTE-HERE
@token = PASTE-TOKEN-HERE

GET https://https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{rg-name}}/providers/Microsoft.Search/searchServices/{{service-name}}/sharedPrivateLinkResources?api-version=2023-11-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

傳送要求。您應該會取得搜尋服務目前所有的共用私人連結資源清單。請確定資源與子資源組合目前沒有共用私人連結。

為 Azure PaaS 資源編寫建立或更新共用私人連結的 PUT 要求。

PUT https://https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{rg-name}}/providers/Microsoft.Search/searchServices/{{service-name}}/sharedPrivateLinkResources/{{shared-private-link-name}}?api-version=2023-11-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

{
    "properties":
     {
        "groupID": "blob",
        "privateLinkResourceId": "/subscriptions/{{subscriptionId}}/resourceGroups/{{rg-name}}/providers/Microsoft.Storage/storageAccounts/{{storage-account-name}}",
        "provisioningState": "",
        "requestMessage": "Please approve this request.",
        "resourceRegion": "",
        "status": ""
     }
}

如果 Azure PaaS 資源位於不同的訂用帳戶中，請使用 Azure CLI 來變更訂用帳戶，然後取得對該訂用帳戶有效的持有人權杖：

az account set --subscription {{Azure PaaS subscription ID}}

az account get-access-token

傳送要求。若要檢查狀態，請重新執行第一個 GET 共用私人連結要求，以監視佈建狀態，該狀態會從「正在更新」轉換為「成功」。

如需快速入門的指示，請參閱使用 PowerShell 管理。

首先，使用 Get-AzSearchSharedPrivateLinkResource 檢閱目前的所有共用私人連結，以確保沒有重複的連結。每個資源和子資源組合只能有一個共用私人連結。

Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>

使用 New-AzSearchSharedPrivateLinkResource 來建立共用私人連結，並將預留位址取代為有效值。此範例適用於 Blob 儲存體。

New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId blob -RequestMessage "Please approve"

重新執行第一個要求以監視佈建狀態，該狀態會從更新轉換為成功。

如需快速入門的指示，請參閱使用 Azure CLI 管理。

首先，使用 az-search-shared-private-link-resource list 來檢閱目前的所有共用私人連結，以確保沒有重複的連結。每個資源和子資源組合只能有一個共用私人連結。

az search shared-private-link-resource list --service-name {{your-search-service-name}} --resource-group {{your-search-service-resource-group}}

使用 az-search-shared-private-link-resource create 進行下一個步驟。此範例適用於 Azure Cosmos DB for NoSQL。

語法區分大小寫，因此請確定群組識別碼為 Sql，且提供者名稱為 Microsoft.DocumentDB。

az search shared-private-link-resource create --name {{your-shared-private-link-name}} --service-name {{your-search-service-name}} --resource-group {{your-search-service-resource-group}} --group-id Sql --resource-id "/subscriptions/{{your-subscription-ID}}/{{your-cosmos-db-resource-group}}/providers/Microsoft.DocumentDB/databaseAccounts/{{your-cosmos-db-account-name}}"

重新執行第一個要求以監視佈建狀態，該狀態會從更新轉換為成功。

共用私人連結建立工作流程

成功時會傳回 202 Accepted 的回應。輸出私人端點的建立程序屬於需長時間執行 (非同步) 的作業。其中涉及到下列資源的部署：

私人端點是以狀態為 "Pending" 的私人 IP 位址進行配置。若為搜尋服務專屬的私人索引子，私人 IP 位址是從配置給執行環境虛擬網路的位址空間取得。在核准私人端點時，從 Azure AI 搜尋服務連接到 Azure 資源的所有通訊皆源自私人 IP 位址和安全的私人連結通道。
資源類型的私人 DNS 區域，以群組識別碼為依據。部署此資源，您便可確針對私人資源進行的所有 DNS 查閱都利用與私人端點相關聯的 IP 位址。

2 - 核准私人端點連線

在 Azure PaaS 端授與私人端點連線的核准。需要資源擁有者明確核准。以下步驟涵蓋使用 Azure 入口網站進行核准，但以下是一些從 Azure PaaS 端以程式設計方式核准連線的連結：

在 Azure 儲存體上，使用「私人端點連線 - Put」
在 Azure Cosmos DB 上，使用「私人端點連線 - Create 或 Update」
在 Azure OpenAI 上，使用「私人端點連線 - Create 或 Update」

使用 Azure 入口網站執行下列步驟：

開啟 Azure PaaS 資源的 [網路] 頁面。文字
尋找列出私人端點連線的區段。下列範例適用於儲存體帳戶。
選取連線，然後選取 [核准]。在 Azure 入口網站中更新狀態可能需要幾分鐘的時間。

核准私人端點之後，Azure AI 搜尋服務會在為其所建的 DNS 區域中建立必要的 DNS 區域對應。

雖然 [網路] 頁面上的私人端點連結為作用中，但不會解析。

選取連結會產生錯誤。顯示狀態訊息 "The access token is from the wrong issuer" 和 must match the tenant associated with this subscription 是因為後端私人端點資源是由 Microsoft 在 Microsoft 管理的租用戶中佈建，而連結的資源 (Azure AI 搜尋服務) 則位於您的租用戶中。依照設計，您無法透過選取私人端點連線連結來存取私人端點資源。

請遵循下一節中的指示以檢查共用私人連結的狀態。

3 - 檢查共用私人連結狀態

在 Azure AI 搜尋服務端，您可以重新瀏覽搜尋服務 [網路] 頁面的 [共用私人存取] 頁面，以確認要求核准。連線狀態應該為已核准。

或者，您也可以使用「共用私人用連結資源 - Get」來取得連線狀態。

az rest --method get --uri https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/contoso/providers/Microsoft.Search/searchServices/contoso-search/sharedPrivateLinkResources/blob-pe?api-version=2024-07-01

此 API 會傳回 JSON，JSON 的連線狀態會顯示在 "properties" 區段底下的 "status"。下面是儲存體帳戶的範例。

{
      "name": "blob-pe",
      "properties": {
        "privateLinkResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/contoso/providers/Microsoft.Storage/storageAccounts/contoso-storage",
        "groupId": "blob",
        "requestMessage": "please approve",
        "status": "Approved",
        "resourceRegion": null,
        "provisioningState": "Succeeded"
      }
}

如果資源的佈建狀態 (properties.provisioningState) 為 "Succeeded" (已成功)，而連線狀態 (properties.status) 為 "Approved" (已核准)，則表示共用私人連結資源正常運作，且可將索引子設定為透過私人端點通訊。

4 - 設定索引子在私人環境中執行

索引子執行作業會在搜尋服務專屬的私人環境中執行，或是內部用來卸載多個客戶的昂貴技能處理作業的多租用戶環境中執行。

執行環境是公開透明的，但當您開始制訂防火牆規則或建立私人連線之後，便必須將索引子執行作業納入考量。針對私人連線，請將索引子執行設定為一律在私人環境中執行。

此步驟會示範如何使用 REST API 將索引子設定為在私人環境中執行。您也可以使用 Azure 入口網站中的 JSON 編輯器來設定執行環境。

注意

您可以在私人端點連線獲核准之前先執行此步驟。不過在私人端點連線顯示為已核准之前，任何嘗試與安全資源 (例如儲存體帳戶) 進行通訊的現有索引子，最終都會處於暫時性失敗的狀態，且無法建立新的索引子。

請依一般做法建立資料來源定義、索引和技能 (如有使用)。使用共用的私人端點時，在這些定義中所有屬性都相同。

建立索引子，該索引子需指向您在上一個步驟中建立的資料來源、索引和技能。此外，請將索引子 executionEnvironment 設定屬性設為 private，強制索引子在私人執行環境中執行。

{
    "name": "indexer",
    "dataSourceName": "blob-datasource",
    "targetIndexName": "index",
    "parameters": {
        "configuration": {
            "executionEnvironment": "private"
        }
    },
    "fieldMappings": []
}

成功建立索引子之後，索引子應會透過私人端點連線至 Azure 資源。您可以使用索引子狀態 API 來監視索引子的狀態。

注意

如果您已經有現有的索引器，您可以透過 PUT API 更新它們，方法是在 Azure 入口網站中將設定executionEnvironment為 private 或使用 JSON 編輯器。

5 - 測試共用的私人連結

如果您尚未這麼做，請確認您的 Azure PaaS 資源是否會拒絕來自公用網際網路的連線。如果可接受連線，請檢閱 Azure PaaS 資源 [網路] 頁面中的 DNS 設定。
選擇可叫用輸出要求案例的工具，例如私人端點的索引子連線。一個簡單的選擇是使用匯入資料精靈，但您也可以嘗試使用 REST 用戶端和 REST API 以獲得更高的精確度。假設您的搜尋服務並未針對私人連線進行設定，則搜尋的 REST 用戶端連線可透過公用網際網路通訊。
將連接字串設定為私人 Azure PaaS 資源。共用私人連結的連接字串格式不會變更。搜尋服務會在內部叫用共用的私人連結。

對於索引子工作負載，連接字串位於資料來源定義中。資料來源的範例可能如下所示：
```
 {
   "name": "my-blob-ds",
   "type": "azureblob",
   "subtype": null,
   "credentials": {
     "connectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=..."
   }
```

針對索引子工作負載，請記得在索引子定義中設定執行環境。索引子定義的範例可能如下所示：

"name": "indexer",
"dataSourceName": "my-blob-ds",
"targetIndexName": "my-index",
"parameters": {
   "configuration": {
       "executionEnvironment": "private"
       }
   },
"fieldMappings": []
}

執行索引子。如果索引子執行成功且已填入搜尋索引，共用的私人連結就會正常運作。

疑難排解

如果索引子建立失敗，並顯示「資料來源認證無效」，在為連線進行偵錯之前，請先檢查共用私人連結的核准狀態。如果狀態為 Approved，請檢查 properties.provisioningState 屬性。如果是 Incomplete，則可能會有基礎相依性的問題。在此情況下，請重新發出 PUT 要求以重新建立共用的私人連結。您可能也會需要重複進行核准步驟。
如果索引子持續或間歇性失敗，請檢查索引子上的 executionEnvironment 屬性。值應該設定為 private。如果您未設定此屬性，而且索引子以前曾成功執行，這是由於搜尋服務自主使用了私人環境。如果系統負載不足，搜尋服務就會將處理移出多租用戶環境。
如果您在建立共用的私人連結時收到錯誤訊息，請檢查服務限制，確定尚未超過您階層的配額。

下一步

深入瞭解私人端點和其他安全連線方法：

共用方式為