依狀態擷取金鑰

透過過濾 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 值開始。

舉例來說，您的 Key Protect 實例中總共儲存了 3000 個金鑰，但當您發出 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 值是以零起始，這表示資料集中的第 10 個加密金鑰位於偏移 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>"