按状态检索密钥

通过对 Key Protect 实例中特定密钥的状态进行过滤，可以检索处于指定状态的密钥。

例如，您的 Key Protect 实例中可能有处于活动，已暂挂和已破坏状态的密钥，但您仅希望在查看密钥列表时检索处于活动状态的密钥。

有关密钥状态的更多信息，请参阅 密钥状态和过渡。

在创建现有密钥或将现有密钥导入到服务中之后，您可以使用两个选项来查看密钥。 第一个选项 通过资源列表查看键 适用于除已分配 细颗粒度访问 的键以外的所有键。 有关如何查看具有细颗粒度访问权的密钥的信息，请查看 查看细颗粒度访问密钥 IAM。

检索键列表

对于高级视图，可以通过向以下端点发出 GET 调用，浏览在供应的 Key Protect 实例中管理的密钥。

https://<region>.kms.cloud.ibm.com/api/v2/keys

1. 检索认证凭证以使用服务中的密钥。

2. 通过运行以下 curl 命令来查看有关密钥的常规特征。

   $ curl -X GET \
       "https://<region>.kms.cloud.ibm.com/api/v2/keys" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: Bearer <IAM_token>" \
       -H "bluemix-instance: <instance_ID>" \
       -H "x-kms-key-ring: <key_ring_ID>" \
       -H "correlation-id: <correlation_ID>"
   

   根据表 1 中的信息替换示例请求中的变量。 有关查看密钥集合 (包括搜索密钥的功能) 时可用的可选参数的更多信息，请参阅 有关 List keys 方法的 API 文档。

成功的 GET api/v2/keys 请求会返回 Key Protect 服务实例中可用的密钥的集合。

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 2
    },
    "resources": [
        {
            "id": "02fd6835-6001-4482-a892-13bd2085f75d",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Root-key",
            "state": 1,
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
            "createdBy": "...",
            "creationDate": "2020-03-11T16:30:06Z",
            "lastUpdateDate": "2020-03-11T16:30:06Z",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "extractable": false,
            "imported": true,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        },
        {
            "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Standard-key",
            "state": 1,
            "expirationDate": "2020-03-14T03:50:12Z",
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "createdBy": "...",
            "creationDate": "2020-03-12T03:50:12Z",
            "lastUpdateDate": "2020-03-12T03:50:12Z",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "extractable": true,
            "imported": false,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        }
    ]
}

默认情况下，GET api/v2/keys 会返回前 200 个键，但您可以在查询时使用 limit 参数调整这一限制。 要了解有关 limit 和 offset 的更多信息，请参阅检索密钥子集。

未看到完整的密钥列表? 您可能需要使用 limit 和 offset，或者与管理员一起检查，以确保为您分配了对实例中密钥的正确级别访问权。 要了解更多信息，请参阅 无法查看或列出密钥。

检索密钥子集

通过在查询时指定 limit 和 offset 参数，可检索密钥子集，从指定的 offset 值开始。

例如，您可能有 3000 个密钥存储在 Key Protect 实例中，但您想在 GET /keys 请求时检索 200 - 300 个密钥。

您可以使用以下示例请求来检索一组不同的密钥。

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?offset=<offset>&limit=<limit>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

根据下表替换请求中的 limit 和 offset 变量。

Offset 是数据集中特定密钥的位置。 offset 值从 0 开始，这意味着数据集中的第 10 个加密密钥位于 offset 9。

按状态检索密钥

通过在查询时指定 state 参数，可以检索处于指定状态的密钥。

例如，您的 Key Protect 实例中可能有处于活动状态，已暂挂状态和已破坏状态的密钥，但您仅希望在发出 GET /keys 请求时检索处于活动状态的密钥。

状态查询参数采用从 0 到 5 的整数列表，以逗号分隔，不含空格或尾部逗号。 有关密钥状态的更多信息，请参阅 密钥状态和过渡。

您可以使用以下示例请求来检索一组不同的密钥。

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?state=<state_integers>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

根据下表替换请求中的 state 变量。

有关使用说明，请查看以下示例，了解如何设置 state 查询参数。

按可抽取值检索密钥

通过在查询时指定 extractable 参数，您可以检索其物料可以离开服务的密钥。

例如，您可能在 Key Protect 实例中同时具有标准密钥和根密钥，但您只希望在发出 GET /keys 请求时使用可抽取的密钥材料来检索密钥。

可抽取查询参数采用布尔值。

您可以使用以下示例请求来检索一组不同的密钥。

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?extractable=<extractable>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

根据下表替换请求中的 extractable 变量。

有关使用说明，请查看以下示例，了解如何设置 extractable 查询参数。

对键列表排序

在基于一个或多个键属性返回的查询字符串 对密钥列表进行排序 中使用 sort 参数。 要按属性降序排序，请以 "-" 作为术语的前缀。要对多个键属性进行排序，请使用逗号来分隔每个属性。 逗号分隔列表中的第一个属性将在下一个属性之前进行求值。

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?sort=<sort-value>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"