版本：Cloud 开发指南

阿里云对象存储

Zilliz Cloud 支持与阿里云对象存储 OSS 集成。

该存储集成可用于：

📘说明

此功能仅限企业版项目使用。

GPQdwo63IhxSjqbk9vkcdZQXngM

开始前

要将 Zilliz Cloud 与阿里云对象存储 OSS 集成，您需要拥有组织管理员或项目管理员权限。如果您权限不足，请联系 Zilliz Cloud 管理员。
您需要具备阿里云 RAM 管理员权限。有关更多信息，请参考 RAM 基本概念。

步骤 1：集成基础设置

integrate-with-oss-1

登录 Zilliz Cloud 控制台。

进入目标项目，点击左侧导航栏的集成中心。

在阿里云对象存储服务（OSS）区域，点击 + 添加配置。

在弹出的对话框中，完成基础设置：

配置名称：为此集成设置一个唯一名称（如：bucket_for_backup）。
配置描述（可选）：为此集成添加描述（如：for export backup file）。

Bucket 权限：选择 Zilliz Cloud 对您的对象存储桶具有的访问级别。下表说明了这些选项。

权限	说明
只读	Zilliz Cloud 只能从存储桶中读取文件。用于为 External Collections 提供支持的 External volumes。
读写	Zilliz Cloud 既可以从 bucket 中读取数据，也可以向 bucket 中写入数据。用于导出备份文件、转发审计日志或转发访问日志。

继续执行步骤 2。

步骤 2：设置 OSS 存储空间

integrate-with-oss-2

登录 OSS 管理控制台。

在左侧导航栏，单击 Bucket 列表，然后单击创建 Bucket。

在创建 Bucket 面板，按如下说明配置各项参数。

Bucket 名称：为您的 OSS 存储空间设置一个唯一名称。
地域：指定存储空间所在的云地域。注意，存储空间所在地域必须和目标 Zilliz Cloud 集群或 Volume所在的地域相同。有关 Zilliz Cloud 支持的云地域，请参考云服务提供商和地域。
其他设置可以保持默认。配置完成后，点击完成创建。

有关更多创建信息，请参考如何创建存储空间。

返回 Zilliz Cloud 控制台。在创建 OSS 存储空间（Bucket）步骤中，选择刚才创建的 Bucket 名称和 Bucket 地域。然后继续执行步骤 3。

步骤 3：创建权限策略

要使 Zilliz Cloud 访问 OSS 存储空间，您需要创建一个权限策略。该策略应包含必要的操作权限和资源，确保 Zilliz Cloud 能顺利地与您的存储空间进行备份文件的传输。

integrate-with-oss-3

为方便起见，可以使用脚本编辑器来创建权限策略。

在 RAM 控制台，选择权限管理 > 权限策略。

在权限策略页面，单击创建权限策略。

在创建权限策略页面，单击脚本编辑页签。

将 Zilliz Cloud 提供的策略内容复制并粘贴到脚本编辑器中。以下是一个示例脚本策略。具体的策略内容，请以 Zilliz Cloud 控制台中创建权限策略（RAM Policy）步骤提供的内容为准。

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:ListObjects",
        "oss:GetObject",
        "oss:PutObject",
        "oss:GetBucketLocation",
        "oss:HeadBucket"
      ],
      "Resource": [
        "acs:oss:oss-*:*:$bucket",
        "acs:oss:oss-*:*:$bucket/*"
      ]
    }
  ]
}

📘说明

$bucket 应替换为您实际的 OSS 存储空间名称。

在创建权限策略页面，单击确定。

在创建权限策略对话框，输入权限策略名称和备注，然后单击确定。

步骤 4：创建 RAM 角色

创建 RAM 角色，并将步骤 3 中定义的权限策略赋予该角色。

在 RAM 控制台，选择角色 > 创建角色。

在创建角色页面，选择可信实体类型为阿里云账号，然后单击下一步。

设置角色信息并单击完成。有关详细配置，请参考创建可信实体为阿里云账号的RAM角色。

在创建完成步骤，点击为角色授权。

在角色详情页面，复制角色 ARN，并将该 ARN 填入 Zilliz Cloud 控制台中创建 RAM 角色步骤的角色 ARN 字段。

integrate-with-oss-4

在角色详情页面的权限管理页签，选择新增授权。

在弹出的新增授权面板，搜索并选择步骤 3 中创建的权限策略，然后点击确认新增授权，最后单击关闭。

在角色详情页面的信任策略页签，编辑信任策略。将 Zilliz Cloud 控制台提供的 JSON 角色信任策略复制并粘贴到编辑器中。

以下是示例角色信任策略。具体的策略内容，请以 Zilliz Cloud 控制台中**创建权限策略（RAM Policy）**步骤提供的内容为准。

{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "zilliz-data-service"
        }
      },
      "Effect": "Allow",
      "Principal": {
        "RAM": [
          "acs:ram::1541183371417731:root"
        ]
      }
    }
  ],
  "Version": "1"
}

点击保存信任策略。然后继续执行步骤 5。

integrate-with-oss-5

步骤 5：校验并创建集成

在 Zilliz Cloud 控制台，点击校验集成，验证当前配置的存储空间和 RAM 角色是否有效。

校验通过后，点击创建。

之后您便可以将备份文件导出到您的阿里云 OSS。有关导出的具体步骤，请参考导出备份文件。

调用接口创建存储集成

除了在 Zilliz Cloud 控制台上进行操作之外，您还可以调用接口创建存储集成。

创建 OSS 存储空间。

更多详情，可参考上面的设置 OSS 存储空间小节或创建存储空间。

生成鉴权材料。

export BASE_URL="https://api.cloud.zilliz.com.cn"
export TOKEN="YOUR_API_KEY"

curl --request POST \
--url "${BASE_URL}/v2/storageIntegrations/authorizationMaterials" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "projectId": "proj-xxxxxxxxxxxxxxxxxxxxxx",
    "regionId": "ali-cn-hangzhou",
    "bucketName": "zilliz-bucket-for-integration-0819"
}'

根据上述请求，Zilliz Cloud 会生成您在阿里云控制台上创建权限策略及 RAM 角色时所需的凭据。返回的响应如下：

{
  "code": 0,
  "data": {
    "readonly": "{...}",
    "readwrite": "{...}",
    "ramPolicy": "{...}",
    "trustPolicy": "{...}",
    "zillizAccount": "306787409409",
    "externalId": "zilliz-external-AbCdEf12345678"
  }
}

关于请求及响应中各字段的说明，可以参考生成 Storage Integration 授权材料。

使用返回的 `readonly`、`readwrite`、`ramPolicy`、`trustPolicy` 及 `zillizAccount` 创建 RAM 角色，并为其添加必要的权限，使其可以操作您的 OSS 存储空间。

请记录下已创建的 RAM 角色 ARN，其格式类似 acs:ram::1234567890123456:root。关于如何创建 RAM 角色，可以参考创建权限策略及创建 RAM 角色两小节的内容。

验证使用上述凭据创建的 RAM 角色是否可以正常访问您的 OSS 存储空间。

在请求中，您需要将 externalCred.roleArn 设置为上一步获得的 RAM 角色 ARN，并将 externalCred.externalId 设置为生成的授权材料中的 externalId。

curl --request POST \
--url "${BASE_URL}/v2/storageIntegrations/validate" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "projectId": "proj-xxxxxxxxxxxxxxxxxxxxxx",
    "regionId": "ali-cn-hangzhou",
    "bucketName": "my-bucket",
    "externalCred": {
        "roleArn": "acs:ram::1234567890123456:root",
        "externalId": "zilliz-external-AbCdEf12345678"
    }
}'

验证成功的响应如下：

{
    "code": 0,
    "data": {
        "success": true,
        "message": ""
    }
}

关于请求及响应中各字段的说明，可以参考校验 Storage Integration。

创建存储集成。

此请求在验证请求的基础上增加了 description 参数。

curl --request POST \
--url "${BASE_URL}/v2/storageIntegrations" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "projectId": "proj-xxxxxxxxxxxxxxxxxxxxxx",
    "name": "analytics-oss",
    "description": "Alibaba OSS bucket for external tables",
    "regionId": "ali-cn-hangzhou",
    "bucketName": "my-bucket",
    "externalCred": {
        "roleArn": "acs:ram::1234567890123456:root",
        "externalId": "zilliz-external-AbCdEf12345678"
    }
}'

上述请求的响应格式如下：

{
    "code": 0,
    "data": {
        "integrationId": "integ-xxxxxxxxxxxxxxxxxxx",
        "name": "analytics-oss"
    }
}

关于请求及响应中各字段的说明，可以参考创建 Storage Integration。

管理集成

集成添加完成后，您可以查看其详细信息或根据需要删除该集成。

integrate-with-oss-6

获取集成 ID

如果您需要使用 RESTful API 接口导出文件到您集成到 Zilliz Cloud 的对象存储桶中，您可以单击查看详情查看该对象存储桶的集成详情并复制该桶的集成 ID。

除此之外，您还可以执行如下命令获取集成 ID。

export TOKEN="YOUR_API_KEY"

curl --request GET \
--url "${BASE_URL}/v2/storageIntegrations?projectId=proj-xxxxxxxxxxxxxxxxxxxxxx" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json"

上述请求的响应如下：

{
    "code": 0,
    "data": {
        "storageIntegrations": [
            {
                "integrationId": "integ-xxxxxxxxxxxxxxxxxxx",
                "name": "analytics-oss",
                "status": "ACTIVE",
                "message": "",
                "regionId": "ali-cn-hangzhou",
                "bucketName": "my-bucket"
            }
        ],
        "count": 1,
        "currentPage": 1,
        "pageSize": 10
    }
}

关于请求及响应中各字段的说明，可以参考列出 Storage Integration。

查看集成详情

您还可以执行如下命令查看指定集成的详情。

export integrationId="integ-xxxxxxxxxxxxxxxxxxx"

curl --request GET \
--url "${BASE_URL}/v2/storageIntegrations/${integrationId}" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json"

上述请求的响应如下：

{
    "code": 0,
    "data": {
        "integrationId": "integ-xxxxxxxxxxxxxxxxxxx",
        "name": "analytics-oss",
        "description": "Alibaba OSS bucket for external tables",
        "status": "ACTIVE",
        "message": "",
        "regionId": "ali-cn-hangzhou",
        "bucketName": "my-bucket",
        "externalCred": {
            "roleArn": "acs:ram::1234567890123456:root",
            "externalId": "zilliz-external-AbCdEf12345678"
        },
        "createTime": "2024-07-30T16:49:50Z"
    }
}

关于请求及响应中各字段的说明，可以参考查看 Storage Integration。

删除集成

除了可以在 Zilliz Cloud 控制台上单击删除按钮之外，您还可以执行如下命令来删除指定集成。

export integrationId="integ-xxxxxxxxxxxxxxxxxxx"

curl --request DELETE \
--url "${BASE_URL}/v2/storageIntegrations/${integrationId}" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json"

上述请求的响应如下：

{
    "code": 0,
    "data": {
        "integrationId": "integ-xxxxxxxxxxxxxxxxxxx",
        "name": "analytics-oss"
    }
}

关于请求及响应中各字段的说明，可以参考删除 Storage Integration。

开始前​

步骤 1：集成基础设置​

登录 Zilliz Cloud 控制台。

进入目标项目，点击左侧导航栏的集成中心。

在**阿里云对象存储服务（OSS）**区域，点击 + 添加配置。

在弹出的对话框中，完成基础设置：

继续执行步骤 2。

步骤 2：设置 OSS 存储空间​

登录 OSS 管理控制台。

在左侧导航栏，单击 Bucket 列表，然后单击创建 Bucket。

在创建 Bucket 面板，按如下说明配置各项参数。

返回 Zilliz Cloud 控制台。在**创建 OSS 存储空间（Bucket）**步骤中，选择刚才创建的 Bucket 名称 和 Bucket 地域。然后继续执行步骤 3。

步骤 3：创建权限策略​

在 RAM 控制台，选择权限管理 > 权限策略。

在权限策略页面，单击创建权限策略。

在创建权限策略页面，单击脚本编辑页签。

将 Zilliz Cloud 提供的策略内容复制并粘贴到脚本编辑器中。 以下是一个示例脚本策略。具体的策略内容，请以 Zilliz Cloud 控制台中**创建权限策略（RAM Policy）**步骤提供的内容为准。

在创建权限策略页面，单击确定。

在创建权限策略对话框，输入权限策略名称和备注，然后单击确定。

步骤 4：创建 RAM 角色​

在 RAM 控制台，选择角色 > 创建角色。

在创建角色页面，选择可信实体类型为阿里云账号，然后单击下一步。

设置角色信息并单击完成。有关详细配置，请参考创建可信实体为阿里云账号的RAM角色。

在创建完成步骤，点击为角色授权。

在角色详情页面，复制角色 ARN，并将该 ARN 填入 Zilliz Cloud 控制台中创建 RAM 角色步骤的 角色 ARN 字段。

在角色详情页面的权限管理页签，选择新增授权。

在弹出的新增授权面板，搜索并选择步骤 3 中创建的权限策略，然后点击确认新增授权，最后单击关闭。

在角色详情页面的信任策略页签，编辑信任策略。将 Zilliz Cloud 控制台提供的 JSON 角色信任策略复制并粘贴到编辑器中。

点击保存信任策略。然后继续执行步骤 5。

步骤 5：校验并创建集成​

在 Zilliz Cloud 控制台，点击校验集成，验证当前配置的存储空间和 RAM 角色是否有效。

校验通过后，点击创建。

调用接口创建存储集成​

创建 OSS 存储空间。

生成鉴权材料。

使用返回的 readonly、readwrite、ramPolicy、trustPolicy 及 zillizAccount 创建 RAM 角色，并为其添加必要的权限，使其可以操作您的 OSS 存储空间。

验证使用上述凭据创建的 RAM 角色是否可以正常访问您的 OSS 存储空间。

创建存储集成。

管理集成​

获取集成 ID​

查看集成详情​

删除集成​

开始前

步骤 1：集成基础设置

在阿里云对象存储服务（OSS）区域，点击 + 添加配置。

步骤 2：设置 OSS 存储空间

返回 Zilliz Cloud 控制台。在创建 OSS 存储空间（Bucket）步骤中，选择刚才创建的 Bucket 名称和 Bucket 地域。然后继续执行步骤 3。

步骤 3：创建权限策略

将 Zilliz Cloud 提供的策略内容复制并粘贴到脚本编辑器中。以下是一个示例脚本策略。具体的策略内容，请以 Zilliz Cloud 控制台中创建权限策略（RAM Policy）步骤提供的内容为准。

步骤 4：创建 RAM 角色

在角色详情页面，复制角色 ARN，并将该 ARN 填入 Zilliz Cloud 控制台中创建 RAM 角色步骤的角色 ARN 字段。

步骤 5：校验并创建集成

调用接口创建存储集成

使用返回的 `readonly`、`readwrite`、`ramPolicy`、`trustPolicy` 及 `zillizAccount` 创建 RAM 角色，并为其添加必要的权限，使其可以操作您的 OSS 存储空间。

管理集成

获取集成 ID

查看集成详情

删除集成