Oracle^® ZFS Storage Appliance RESTful API 指南，发行版 OS8.8.x

云服务操作

使用云服务操作管理 Oracle Cloud Infrastructure 对象存储中的设备快照备份。可以列出 Oracle Cloud Infrastructure 对象存储中的目标和备份、删除目标、删除备份、将备份恢复为新设备共享资源，以及取消或重新启动云服务作业。

要创建备份，请参见快照备份操作中的创建快照备份。备份是共享资源快照的完整或增量备份。要创建快照，请参见快照和克隆操作。

云服务操作表中使用以下参数：

format

Oracle Cloud Infrastructure 对象存储中用于保存备份的格式。

format 的值为 zfs 或 tar。如果未为快照备份创建指定 format，则默认为 zfs。zfs 格式既支持文件系统快照又支持 LUN 快照；tar 格式仅支持文件系统快照。有关 zfs 和 tar 格式的更多信息，请参见Oracle ZFS Storage Appliance 管理指南，发行版 OS8.8.x 中的 创建云备份 (CLI)。

backup-id

在 Oracle Cloud Infrastructure 对象存储中保存的设备快照副本的标识符。按照列出云备份所示列出备份时，backup-id 的值为 id 属性的值。

对于完整快照备份，backup-id 的值为 pool_id/snapshot_id，如以下示例中所示：

3e035b7e546e0d02/1cbfdb5ff2259b76

对于增量快照备份，backup-id 的值为 pool_id/child_snapshot_id-parent_snapshot_id，如以下示例中所示：

6913a5703bee98dc/46be95ced54e99d9-667f3eb88fd209e1

target-id

保存备份的 Oracle Cloud Infrastructure 对象存储位置。给定的备份可以保存到多个目标。也就是说，同一个 backup-id 可以出现在不同的 target-id 位置中。

列出备份时，target-id 的值为 target 属性的值。

job-id

正在运行的作业的标识符。按照列出作业所示列出作业时，job-id 的值为 id 属性的值。

表 28  云服务命令

请求 附加到路径 /api/service/v2/services 说明 GET /cloud 列出目标、备份和作业的属性和摘要数据。 PUT /cloud 修改属性。 POST /cloud/targets 创建新的目标。 GET /cloud/targets 列出目标。 GET /cloud/targets/target-id 列出指定目标的属性。 PUT /cloud/targets/target-id 修改指定目标的属性。 DELETE /cloud/targets/target-id 从服务中删除指定的目标。 GET /cloud/backups 列出所有已完成的任何格式的备份。 GET /cloud/backups/format/backup-id/target-id 列出指定的备份。 DELETE /cloud/backups/format/backup-id/target-id 删除指定的备份（提交作业请求）。 POST /cloud/backups/format/backup-id/target-id/restore 恢复指定的备份（提交作业请求）。 GET /cloud/jobs 列出正在运行的作业和最近完成的作业。 GET /cloud/jobs/job-id 列出指定作业的属性。 PUT /cloud/jobs/job-id/cancel 取消指定的正在运行的作业。 PUT /cloud/jobs/job-id/restart 重新启动指定的已中止作业。

启用云服务

要启用云服务，请将 status 设置为 enable，如以下示例中所示。

请求示例：

PUT /api/service/v2/services/cloud HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*
Content-Type: application/json
Content-Length: 22

{ "<status>": "enable" }

查看云服务日志文件

使用以下请求查看云服务的日志文件：

GET /api/log/v1/logs/appliance-kit-cloud:default HTTP/1.1

列出云服务属性

请求示例：

GET /api/service/v2/services/cloud HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

结果示例：

HTTP/1.1 200 OK
Date: Wed, 24 Jul 2019 20:30:59 GMT
Content-Length: 843
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

{
  "service": {
    "href": "/api/service/v2/services/cloud",
    "<status>": "online",
    "tls_version": [
      "TLSv1.1",
      "TLSv1.2"
    ],
    "ciphers": [
      "ECDHE-RSA-AES128-GCM-SHA256",
      "ECDHE-RSA-AES256-GCM-SHA384",
      "DHE-RSA-AES128-GCM-SHA256",
      "DHE-RSA-AES256-GCM-SHA384",
      "AES128-SHA",
      "AES256-SHA",
      "DES-CBC3-SHA"
    ],
    "targets": {
      "href": "/api/service/v2/services/cloud/targets",
      "entries": 2
    },
    "backups": {
      "href": "/api/service/v2/services/cloud/backups",
      "entries": 2548
    },
    "jobs": {
      "href": "/api/service/v2/services/cloud/jobs",
      "entries": 0
    }
  }
}

修改云服务属性

请求示例：

PUT /api/service/v2/services/cloud HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*
Content-Type: application/json
Content-Length: 48

{
    "tls_version": [
        "TLSv1.0","TLSv1.1","TLSv1.2"
    ]
}

列出目标

以下示例列出所有目标。

请求示例：

GET /api/service/v2/services/cloud/targets HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

结果示例：

HTTP/1.1 200 OK
Date: Wed, 24 Jul 2019 21:06:18 GMT
Content-Length: 1086
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

{
    "targets": [{
        "bucket": "pl-test",
        "href": "/api/service/v2/services/cloud/targets/target-id1",
        "id": "target-id1",
        "key": true,
        "location": "https://objectstorage.us-ashburn-1.oraclecloud.com",
        "name": "oci-ashburn",
        "online": true,
        "proxy_host": "",
        "proxy_on": false,
        "proxy_password": false,
        "proxy_user": "",
        "tenancy": "ocid1.tenancy.oc1..tenancy-id",
        "user": "ocid1.user.oc1..user-id"
    },{
        "bucket": "pl-test2",
        "href": "/api/service/v2/services/cloud/targets/target-id2",
        "id": "target-id2",
        "key": true,
        "location": "https://objectstorage.us-phoenix-1.oraclecloud.com",
        "name": "oci-phoenix",
        "online": true,
        "proxy_host": "www-proxy.example.com:80",
        "proxy_on": true,
        "proxy_password": false,
        "proxy_user": "",
        "tenancy": "ocid1.tenancy.oc1..tenancy-id",
        "user": "ocid1.user.oc1..user-id"
    }]
}

以下示例列出指定的目标：

GET /api/service/v2/services/cloud/targets/target-id HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

创建目标

创建云目标需要以下参数。

参数 说明 key Oracle Cloud Infrastructure 账户的 user-id 的用户密钥 tenancy-id Oracle Cloud Infrastructure 账户的租户名称 OCID user-id Oracle Cloud Infrastructure 账户的用户名 OCID

以下示例创建一个目标。

请求示例：

POST /api/service/v2/services/cloud/targets HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=

{
    "name": "oci4",
    "location": "https://objectstorage.us-phoenix-1.oraclecloud.com",
    "user": "ocid1.user.oc1..user-id",
    "bucket": "test-bucket3",
    "tenancy": "ocid1.tenancy.oc1..tenancy-id",
    "key": "key",
    "proxy_on": false,
    "readlimit": -1,
    "writelimit": -1
}

结果示例：

HTTP/1.1 201 Created
Date: Wed, 24 Jul 2019 21:14:39 GMT
Content-Length: 568
X-Zfssa-Service-Api: 2.0
Location: /api/service/v2/services/cloud/targets/target-id
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

{
    "target": {
        "bucket": "test-bucket3",
        "href": "/api/service/v2/services/cloud/targets/target-id",
        "id": "target-id",
        "key": true,
        "location": "https://objectstorage.us-phoenix-1.oraclecloud.com",
        "name": "oci4",
        "proxy_on": false,
        "readlimit": -1,
        "state": "offline",
        "tenancy": "ocid1.tenancy.oc1..tenancy-id",
        "user": "ocid1.user.oc1..user-id",
        "writelimit": -1
    }
}

修改目标

下表显示云目标的可修改属性。

属性 说明 name 此云目标的名称，在每个设备上必须唯一。 proxy_on 如果为 true，则使用代理与 Internet 进行系统通信。 如果 proxy_on 的值为 true，则必须为 proxy_host 提供值。 proxy_host 代理主机名和端口号。 proxy_password 可选。代理密码。 proxy_user 可选。代理用户名。 readlimit 可选。将从云目标中读取数据的最大速率（每秒字节数）。从云中恢复云备份时，使用此值。例如，如果值为 4194304，则将从云目标读取数据的速率限制在每秒 4 MB。如果值为 -1，则意味着不对 I/O 进行限制。 writelimit 可选。将向云目标中写入数据的最大速率（每秒字节数）。将云快照上载到云目标时，使用此值。例如，如果值为 5242880，则将向云目标写入数据的速率限制在每秒 5 MB。如果值为 -1，则意味着不对 I/O 进行限制。

请求示例：

PUT /api/service/v2/services/cloud/targets/target-id HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
User-Agent: curl/7.54.0
Accept: */*
Content-Type: application/json
Content-Length: 19
{
    "proxy_on": true,
    "proxy_host": "www-proxy.example.com:80",
    "readlimit": 4194304,
    "writelimit": 5242880
}

删除目标

删除目标之前，请执行以下检查：

• 检查是否正在执行到此目标的备份。请参见列出作业。

• 确定此目标是否有备份。使用 target 过滤器（如列出云备份所示）列出在此目标上存储的备份。

以下示例从服务中删除指定的云目标。

请求示例：

DELETE /api/service/v2/services/cloud/targets/target-id HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

结果示例：

HTTP/1.1 204 No Content
Date: Wed, 24 Jul 2019 21:20:27 GMT
X-Content-Type-Options: nosniff
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

列出云备份

使用以下查询列出所有已完成的任何格式的备份，越新的备份越先列出。要获取有关正在进行的备份的信息，请参见列出作业。

请求示例：

GET /api/service/v2/services/cloud/backups HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

结果示例：

在此示例中，列出的第一个备份是所列出的第二个备份的子备份。第一个备份的 parent 值与第二个备份的 dataset 值相同 (app-data-fullsnap)，第二个备份的 parent 值为 null。子备份与父备份采用相同的 format。在此示例中，子备份和父备份均采用 tar 格式。

HTTP/1.1 200 OK
Date: Wed, 22 Jan 2020 21:22:40 GMT
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked

{
    "backups": [{
        "target": "target-id2",
        "parent": "app-data-fullsnap",
        "started": "2020-01-06T20:03:32Z",
        "completed": "2020-01-06T20:04:36Z",
        "id": "backup-id2",
        "source": "cloudsnap0",
        "href": "/api/service/v2/services/cloud/backups/tar/backup-id2/target-id2",
        "tier": "standard",
        "dataset": "p1/local/default/app-data@app-data-incsnap",
        "format": "tar",
        "size": 3224982536.0
    },{
        "target": "target-id1",
        "parent": "",
        "started": "2020-01-06T20:01:16Z",
        "completed": "2020-01-06T20:01:17Z",
        "id": "backup-id1",
        "source": "cloudsnap0",
        "href": "/api/service/v2/services/cloud/backups/tar/backup-id1/target-id1",
        "tier": "standard",
        "dataset": "p1/local/default/app-data@app-data-fullsnap",
        "format": "tar",
        "size": 2149988056.0
    }]
}

使用以下请求列出指定的备份：

GET /api/service/v2/services/cloud/backups/format/backup-id/target-id HTTP/1.1

列出云备份查询参数

支持以下查询参数以过滤云备份列表。可以在同一个查询中使用所有参数。在查询参数之间使用 AND 运算 (&)，如表后面的示例中所示。

表 29  用于列出云备份的查询参数

属性 说明 start start 的值为以下值之一： 备份索引。此索引的值比列出云服务属性中所示请求的 backups 部分中的 entries 属性值小 0 到 1。 列出由指定的索引选择的备份，以及在创建指定的备份之后创建的最早备份。 %Y-%m-%dT%H:%M:%SZ 格式的时间。这与 started 和 completed 属性的值所采用的格式相同。此时间可以是当前时间之前的任何实际时间。例如，2019-09-00T00:00:00Z 不是实际时间。 列出在指定时间或其后创建的最早备份。 end end 的值为 %Y-%m-%dT%H:%M:%SZ 格式的时间。这与 started 和 completed 属性的值所采用的格式相同。此时间可以是当前时间之前的任何实际时间。例如，2019-09-00T00:00:00Z 不是实际时间。 列出在指定时间或其前创建的最新备份。 limit 列出的备份数量不超过指定数量。limit 参数没有默认值。 target target 属性的值。列出该目标上的最新备份。 source source 属性的值。列出该源上的最新备份。 dataset @ 前面的 dataset 属性的值。例如，对于数据集 p1/local/default/app-data@app-data-incsnap，指定 p1/local/default/app-data 或 app-data。 列出指定数据集中的最新备份。 注 -  对数据集备份的请求列出名称中包含所请求数据集名称的所有数据集的所有备份。例如，对 p1/local/default/app-data@app-data-incsnap 备份的请求还将返回名为 app-data-incsnap、app-data-incsnap-1 和 myproj-app-data-incsnap 的数据集的备份。 format format 属性的值（zfs 或 tar）。以指定的备份格式列出最新的备份。

以下示例列出从索引编号为 2000 的备份开始的最早备份。如果云服务属性列表的 backups 部分中 entries 属性的值为 2865，则以下示例显示 865 个备份：从备份 2000 到备份 2864。

GET /api/service/v2/services/cloud/backups?start=2000

以下示例仅列出索引编号为 2000 的备份：

GET /api/service/v2/services/cloud/backups?start=2000&limit=1

以下示例列出 500 个在指定时间或其后创建的最早备份：

GET /api/service/v2/services/cloud/backups?start=2019-07-12T00:00:00Z&limit=500

以下示例列出 500 个在指定时间或其前创建的最新备份：

GET /api/service/v2/services/cloud/backups?end=2019-07-12T00:00:00Z&limit=500

以下示例列出在指定的 start 时间或之后（但不晚于指定的 end 时间）创建的所有备份：

GET /api/service/v2/services/cloud/backups?start=2019-07-11T00:00:00Z&end=2019-07-12T00:00:00Z

以下示例列出名称中包含 app-data 且采用 tar 备份格式的任何数据集的最新备份：

GET /api/service/v2/services/cloud/backups?dataset=app-data&format=tar

以下示例列出 target-id 目标上名称中包含 app-data 的任何数据集的最新备份：

GET /api/service/v2/services/cloud/backups?dataset=app-data&target=target-id

以下示例列出具有 cloudsnap0 源的 target-id 目标上名称中包含 app-data 的任何数据集的最新备份：

GET /api/service/v2/services/cloud/backups?dataset=app-data&target=target-id&source=cloudsnap0

删除云备份

删除云备份之前，请执行以下检查：

• 检查是否正在恢复此备份。请参见列出作业。

• 确定此备份是否有子备份。无法删除具有子备份的备份。此备份的子备份的 parent 值与要删除的备份的 dataset 值相同。请参见列出云备份。

以下示例提交一个作业请求，以从 Oracle Cloud Infrastructure 对象存储中删除指定目标上指定备份。设备可以操作它能够访问的任何目标上的任何备份，即使该备份创建于其他设备上也是如此。

将此操作与删除快照备份进行比较，后者说明如何删除设备上的共享资源快照备份。

请求示例：

DELETE /api/service/v2/services/cloud/backups/format/backup-id/target-id HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

结果示例：

{
    "action": "job-id"
}

要查看云备份删除进度，请使用列出作业查看具有上述 job-id 的作业。

恢复云备份

云备份可以在任何能够访问相应云目标的设备上恢复为新克隆的共享资源。

以下示例提交一个作业请求，以恢复指定的备份。指定要将备份恢复到的池和项目，并为新共享资源指定名称。要查看恢复进度，请使用列出作业查看具有所返回 job-id 的作业。

如果为目标设置了 readlimit 属性，则每秒从目标读取的字节数不超过 readlimit 字节。请参见创建目标。

请求示例：

POST /api/service/v2/services/cloud/backups/format/backup-id/target-id/restore HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*
Content-Length: 55

{
    "pool":"p1",
    "project":"default",
    "share": "restore6"
}

结果示例：

{
    "action": "job-id"
}

列出作业

以下示例列出所有正在运行的作业和最近完成的作业，最新的作业最先列出。

请求示例：

GET /api/service/v2/services/cloud/jobs HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

结果示例：

在此示例中，两个备份作业将两个不同的备份保存到同一个目标。

HTTP/1.1 200 OK
Date: Wed, 22 Jan 2020 21:37:52 GMT
Content-Length: 983
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

{
    "jobs": [{
        "href": "/api/service/v2/services/cloud/jobs/job-id2",
        "op": "backup",
        "target": "target-id",
        "targetName": "oci-ashburn",
        "created": "2020-02-06T16:52:42Z",
        "updated": "2020-02-06T16:52:48Z",
        "id": "job-id2",
        "status": "in-progress",
        "rate": 10002432,
        "transferred": 80019456,
        "estimated_size": 43088792088,
        "dataset": "p1/local/default/f-1",
        "backup": "backup-id2",
        "snapshot": "snap3",
        "format": "tar",
        "details": "uploading backup to zfs/backups/tar/backup-id2/000000001"
    },{
        "href": "/api/service/v2/services/cloud/jobs/job-id1",
        "op": "backup",
        "target": "target-id",
        "targetName": "oci-ashburn",
        "created": "2020-02-06T16:52:28Z",
        "updated": "2020-02-06T16:52:48Z",
        "id": "job-id1",
        "status": "in-progress",
        "rate": 1942,
        "transferred": 3884,
        "estimated_size": 0,
        "dataset": "p1/local/default/f-1",
        "backup": "backup-id1",
        "snapshot": "snap2",
        "format": "zfs",
        "details": "uploading backup to zfs/backups/zfs/backup-id1/000000001"
    }]
}

以下示例列出指定的作业：

GET /api/service/v2/services/cloud/jobs/job-id2 HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

列出云备份作业查询参数

支持 start 和 limit 查询参数以过滤云备份作业列表。

• start 参数的值为作业索引。此索引的值比列出云服务属性中所示请求的 jobs 部分中的 entries 属性值小 0 到 1。

• limit 参数的值为要列出的最大作业数。

这两个参数可以在同一个查询中使用。在查询参数之间使用 AND 运算 (&)，如下面的几个示例中所示。

以下示例列出 100 个正在运行的最新作业和最近完成的作业，最新的作业最先列出。

GET /api/service/v2/services/cloud/jobs?limit=100

以下示例仅列出正在运行的最早作业或最近完成的作业。

GET /api/service/v2/services/cloud/jobs?start=0&limit=1

以下示例列出作业索引编号等于或大于 4 的所有正在运行的作业和最近完成的作业，最新的作业最先列出。

GET /api/service/v2/services/cloud/jobs?start=4

取消或重新启动作业

以下示例取消指定的云服务作业。

请求示例：

PUT /api/service/v2/services/cloud/jobs/job-id/cancel HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: */*

结果示例：

HTTP/1.1 202 Accepted
Date: Wed, 24 Jul 2019 21:50:29 GMT
Content-Length: 0
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8

以下示例重新启动指定的云服务作业。

请求示例：

PUT /api/service/v2/services/cloud/jobs/job-id/restart HTTP/1.1
Host: hostname:215
Authorization: Basic Tm8gcGVla2luZyE=
User-Agent: curl/7.54.0
Accept: */*

结果示例：

HTTP/1.1 202 Accepted
Date: Wed, 24 Jul 2019 21:51:08 GMT
Content-Length: 0
X-Zfssa-Service-Api: 2.0
X-Zfssa-Api-Version: 2.0
Content-Type: application/json; charset=utf-8