使用 REST API 管理 Azure AI 搜索服务

在本文中,了解如何使用管理 REST API 创建和配置 Azure AI 搜索服务。 只能保证管理 REST API 会提供对预览功能的抢先访问权限。

管理 REST API 目前以稳定的预览版形式提供。 如果你要访问预览版功能,请务必设置 API 预览版。

所有管理 REST API 都有示例。 如果本文未涵盖某项任务,请参阅 API 参考

先决条件

  • Azure 订阅 - 创建试用版订阅

  • Postman 或其他发送 HTTP 请求的 REST 客户端。

  • Azure CLI,用于为客户端设置安全主体。 必须具有所有者或管理员权限才能创建安全主体。

创建安全主体

将会通过 Microsoft Entra ID 对管理 REST API 调用进行身份验证。 你将需要 REST 客户端的安全主体,以及创建和配置资源的权限。 此部分说明如何创建安全主体和分配角色。

注意

以下步骤摘自将 Azure REST API 与 Postman 配合使用博客文章。

  1. 打开 Azure CLI 的命令行界面。

  2. 登录到 Azure 订阅。

    az login
    
  3. 首先,获取订阅 ID。 在控制台中输入以下命令:

    az account show --query id -o tsv
    
  4. 为安全主体创建资源组,并指定位置和名称。 此示例使用“中国北部”区域。

    az group create -l chinanorth -n MyResourceGroup
    
  5. 创建服务主体并将占位符值替换为有效值。 需要指定描述性的安全主体名称、订阅 ID 和资源组名称。

    请注意,安全主体具有创建或更新 Azure 资源所必需的“所有者”权限。 如果你要管理现有的搜索服务,请改用参与者或“搜索服务参与者”(带引号)。

    az ad sp create-for-rbac --name mySecurityPrincipalName \
                             --role owner \
                             --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName
    

    成功的响应包括“appId”、“password”和“tenant”。 在下一部分,你将为变量“clientId”、“clientSecret”和“tenant”使用这些值。

设置 Postman

如果需要更多详细信息,以下步骤来自这篇博文

  1. 启动新的 Postman 集合并编辑其属性。 在“变量”选项卡中,创建以下变量:

    变量 说明
    clientId 提供在 Microsoft Entra ID 中创建的以前生成的“appID”。
    clientSecret 提供为客户创建的“密码”。
    tenantId 提供在上一步中返回的“租户”。
    subscriptionId 提供订阅的订阅 ID。
    resource 输入 https://management.chinacloudapi.cn/。 此 Azure 资源用于所有控制平面操作。
    bearerToken (留空;令牌以编程方式生成)
  2. 在“授权”选项卡中,选择“持有者令牌”作为类型。

  3. 在“令牌”字段中,指定变量占位符 {{bearerToken}}

  4. 在“预请求脚本”选项卡中,粘贴以下脚本:

    pm.test("Check for collectionVariables", function () {
        let vars = ['clientId', 'clientSecret', 'tenantId', 'subscriptionId'];
        vars.forEach(function (item, index, array) {
            console.log(item, index);
            pm.expect(pm.collectionVariables.get(item), item + " variable not set").to.not.be.undefined;
            pm.expect(pm.collectionVariables.get(item), item + " variable not set").to.not.be.empty; 
        });
    
        if (!pm.collectionVariables.get("bearerToken") || Date.now() > new Date(pm.collectionVariables.get("bearerTokenExpiresOn") * 1000)) {
            pm.sendRequest({
                url: 'https://login.chinacloudapi.cn/' + pm.collectionVariables.get("tenantId") + '/oauth2/token',
                method: 'POST',
                header: 'Content-Type: application/x-www-form-urlencoded',
                body: {
                    mode: 'urlencoded',
                    urlencoded: [
                        { key: "grant_type", value: "client_credentials", disabled: false },
                        { key: "client_id", value: pm.collectionVariables.get("clientId"), disabled: false },
                        { key: "client_secret", value: pm.collectionVariables.get("clientSecret"), disabled: false },
                        { key: "resource", value: pm.collectionVariables.get("resource") || "https://management.chinacloudapi.cn/", disabled: false }
                    ]
                }
            }, function (err, res) {
                if (err) {
                    console.log(err);
                } else {
                    let resJson = res.json();
                    pm.collectionVariables.set("bearerTokenExpiresOn", resJson.expires_on);
                    pm.collectionVariables.set("bearerToken", resJson.access_token);
                }
            });
        }
    });
    
  5. 保存集合。

现在 Postman 已设置,可以发送与本文所述类似的 REST 调用。 你将在适用情况下更新终结点和请求正文。

列出搜索服务

返回当前订阅下的所有搜索服务,包括详细的服务信息:

GET https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

创建或更新服务

在当前订阅下创建或更新搜索服务。 此示例为搜索服务名称和区域使用变量,这些变量尚未定义。 请直接提供名称,或者向集合添加新变量。

PUT https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
  "location": "{{region}}",
  "sku": {
    "name": "basic"
  },
  "properties": {
    "replicaCount": 1,
    "partitionCount": 1,
    "hostingMode": "default"
  }
}

创建 S3HD 服务

若要创建 S3HD 服务,请使用组合 -Sku-HostingMode 属性。 将“sku”设置为 Standard3,“hostingMode”设置为 HighDensity

PUT https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
  "location": "{{region}}",
  "sku": {
    "name": "Standard3"
  },
  "properties": {
    "replicaCount": 1,
    "partitionCount": 1,
    "hostingMode": "HighDensity"
  }
}

为数据平面配置基于角色的访问

适用于:搜索索引数据参与者、搜索索引数据读取者、搜索服务参与者

在此步骤中配置搜索服务,以识别提供 OAuth2 访问令牌的数据请求上的授权头。

若要对数据平面操作使用 Azure 基于角色的访问控制 (Azure RBAC),请将“authOptions”设置为“aadOrApiKey”,然后发送请求。

如果要以独占方式使用 Azure RBAC,请通过继续第二个请求来关闭 API 密钥身份验证,这次将“disableLocalAuth”设置为“true”。

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
  "properties": {
    "disableLocalAuth": false,
    "authOptions": {
      "aadOrApiKey": {
        "aadAuthFailureMode": "http401WithBearerChallenge"
      }
    }
  }
}

强制实施客户管理的密钥策略

如果使用的是客户管理的加密,且希望搜索服务报告其合规性状态,则可以启用“encryptionWithCMK”并将“强制”设置为“启用”。

启用此策略后,如果未提供加密密钥,则创建包含敏感数据(例如数据源中的连接字符串)的对象的任何 REST 调用将失败:"Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
  "properties": {
    "encryptionWithCmk": {
      "enforcement": "Enabled",
      "encryptionComplianceStatus": "Compliant"
    },
  }
}

(预览)禁用将数据推送到外部资源的工作负载

Azure AI 搜索在更新知识存储、保存调试会话状态或缓存扩充内容时写入外部数据源。 以下示例在服务级别禁用这些工作负载。

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
{
  "properties": {
    "disabledDataExfiltrationOptions": [
      "All"
    ]
  }
}

后续步骤

配置搜索服务后,接下来的步骤包括使用门户、REST API 或 .NET SDK 创建索引查询索引