共用方式為


KeyClient 類別

用於管理保存庫金鑰的高階介面。

繼承
azure.keyvault.keys._shared.client_base.KeyVaultClientBase
KeyClient

建構函式

KeyClient(vault_url: str, credential: TokenCredential, **kwargs)

參數

vault_url
str
必要

用戶端將存取之保存庫的 URL。 這也稱為保存庫的「DNS 名稱」。 您應該驗證此 URL 參考有效的金鑰保存庫或受控 HSM 資源。 如需詳細資訊,請參閱<https://aka.ms/azsdk/blog/vault-uri>。

credential
TokenCredential
必要

物件,可為保存庫提供存取權杖,例如來自的認證 identity

api_version
ApiVersion

要使用的服務 API 版本。 預設為最新的 。

verify_challenge_resource
bool

是否要驗證驗證挑戰資源符合金鑰保存庫或受控 HSM 網域。 預設值為 True。

方法

backup_key

以受保護的形式備份金鑰,僅供 Azure 金鑰保存庫使用。

需要金鑰/備份許可權。

這是為了允許將金鑰從一個保存庫複製到另一個保存庫。 這兩個保存庫都必須由相同的 Azure 訂用帳戶擁有。 此外,無法跨地理政治界限執行備份/還原。 例如,美國區域中保存庫的備份無法還原到歐盟區域中的保存庫。

begin_delete_key

刪除金鑰及其密碼編譯資料的所有版本。

需要金鑰/刪除許可權。 當此方法傳回金鑰保存庫開始刪除金鑰時。 在已啟用虛刪除的保存庫中,刪除可能需要幾秒鐘的時間。 因此,此方法會傳回輪詢器,讓您等候刪除完成。

begin_recover_deleted_key

將已刪除的金鑰復原至其最新版本。 只能在已啟用虛刪除的保存庫中進行。

需要金鑰/復原許可權。

當此方法傳回金鑰保存庫開始復原金鑰時。 復原可能需要幾秒鐘的時間。 因此,此方法會傳回輪詢器,讓您等候復原完成。 只有在您想要立即在另一個作業中使用復原的金鑰時,才需要等候。

close

關閉用戶端所開啟的通訊端。

使用用戶端做為內容管理員時,不需要呼叫這個方法。

create_ec_key

建立新的橢圓曲線索引鍵;如果 name 已在使用中,請建立新版的金鑰。

需要金鑰/建立權限。

create_key

建立金鑰,或者,如果 name 已在使用中,請建立新版的金鑰。

需要金鑰/建立許可權。

create_oct_key

建立新的八位序列 (對稱) 金鑰,如果 name 正在使用中,請建立新版本的金鑰。

需要金鑰/建立權限。

create_rsa_key

建立新的 RSA 金鑰;如果 name 已在使用中,請建立新版的金鑰

需要金鑰/建立權限。

get_cryptography_client

CryptographyClient取得指定索引鍵的 。

get_deleted_key

取得已刪除的金鑰。 只能在已啟用虛刪除的保存庫中進行。

需要金鑰/取得許可權。

get_key

取得金鑰的屬性,如果是非對稱金鑰,則為其公開資料。

需要金鑰/取得許可權。

get_key_rotation_policy

取得金鑰保存庫金鑰的輪替原則。

get_random_bytes

從受控 HSM 取得要求的隨機位元組數目。

import_key

匯入外部建立的金鑰。

需要金鑰/匯入許可權。 如果 name 已在使用中,金鑰將會匯入為新版本。

list_deleted_keys

列出所有已刪除的金鑰,包括每個的公用部分。 只能在已啟用虛刪除的保存庫中進行。

需要金鑰/清單許可權。

list_properties_of_key_versions

列出金鑰版本的識別碼和屬性。

需要金鑰/清單許可權。

list_properties_of_keys

列出保存庫中所有金鑰的識別碼和屬性。

需要金鑰/清單許可權。

purge_deleted_key

永久刪除已刪除的金鑰。 只有在已啟用虛刪除的保存庫中才可行。

執行無法復原的指定金鑰刪除,而無法復原。 如果 recovery_level 未指定 「可清除」,則無法使用此作業。 只有在清除索引 scheduled_purge_date 鍵之前,才需要這個方法。

需要金鑰/清除許可權。

release_key

釋放金鑰。

發行金鑰作業適用于所有金鑰類型。 目標金鑰必須標示為可匯出。 此作業需要金鑰/發行許可權。

restore_key_backup

將金鑰備份還原至保存庫。

需要金鑰/還原許可權。

這會匯入金鑰的所有版本,其中包含其名稱、屬性和存取控制原則。 如果金鑰的名稱已在使用中,還原它將會失敗。 此外,目標保存庫必須擁有與來源保存庫相同的 Microsoft Azure 訂用帳戶。

rotate_key

藉由產生新版本的金鑰,根據金鑰原則輪替金鑰。

此作業需要金鑰/輪替許可權。

send_request

使用用戶端的現有管線執行網路要求。

要求 URL 可以相對於保存庫 URL。 除非另有指定,否則用於要求的服務 API 版本與用戶端的版本相同。 如果回應為錯誤,則這個方法不會引發;若要引發例外狀況,請在傳回的回應物件上呼叫 raise_for_status () 。 如需如何使用此方法傳送自訂要求的詳細資訊,請參閱 https://aka.ms/azsdk/dpcodegen/python/send_request

update_key_properties

變更金鑰的屬性, (不是其密碼編譯資料) 。

需要金鑰/更新許可權。

update_key_rotation_policy

更新金鑰保存庫金鑰的輪替原則。

此作業需要金鑰/更新許可權。

backup_key

以受保護的形式備份金鑰,僅供 Azure 金鑰保存庫使用。

需要金鑰/備份許可權。

這是為了允許將金鑰從一個保存庫複製到另一個保存庫。 這兩個保存庫都必須由相同的 Azure 訂用帳戶擁有。 此外,無法跨地理政治界限執行備份/還原。 例如,美國區域中保存庫的備份無法還原到歐盟區域中的保存庫。

backup_key(name: str, **kwargs) -> bytes

參數

name
str
必要

要備份的金鑰名稱

傳回類型

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

begin_delete_key

刪除金鑰及其密碼編譯資料的所有版本。

需要金鑰/刪除許可權。 當此方法傳回金鑰保存庫開始刪除金鑰時。 在已啟用虛刪除的保存庫中,刪除可能需要幾秒鐘的時間。 因此,此方法會傳回輪詢器,讓您等候刪除完成。

begin_delete_key(name: str, **kwargs) -> LROPoller[DeletedKey]

參數

name
str
必要

要刪除的索引鍵名稱。

傳回

刪除金鑰作業的輪詢器。 輪詢器 的結果 方法會傳回 , DeletedKey 而不需要等候刪除完成。 如果保存庫已啟用虛刪除,而且您想要使用 purge_deleted_key 永久刪除金鑰,請先呼叫輪詢器的 wait 方法。 它會封鎖直到刪除完成為止。 wait方法需要金鑰/取得許可權。

傳回類型

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

begin_recover_deleted_key

將已刪除的金鑰復原至其最新版本。 只能在已啟用虛刪除的保存庫中進行。

需要金鑰/復原許可權。

當此方法傳回金鑰保存庫開始復原金鑰時。 復原可能需要幾秒鐘的時間。 因此,此方法會傳回輪詢器,讓您等候復原完成。 只有在您想要立即在另一個作業中使用復原的金鑰時,才需要等候。

begin_recover_deleted_key(name: str, **kwargs) -> LROPoller[KeyVaultKey]

參數

name
str
必要

要復原的已刪除金鑰名稱

傳回

復原作業的輪詢器。 輪詢器 的結果 方法會傳回已 KeyVaultKey 復原,而不需要等候復原完成。 如果您想要立即使用復原的金鑰,請呼叫輪詢器的 wait 方法,這會封鎖直到金鑰可供使用為止。 wait方法需要金鑰/取得許可權。

傳回類型

例外狀況

close

關閉用戶端所開啟的通訊端。

使用用戶端做為內容管理員時,不需要呼叫這個方法。

close() -> None

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

create_ec_key

建立新的橢圓曲線索引鍵;如果 name 已在使用中,請建立新版的金鑰。

需要金鑰/建立權限。

create_ec_key(name: str, **kwargs) -> KeyVaultKey

參數

name
str
必要

新索引鍵的名稱。

curve
KeyCurveNamestrNone

橢圓曲線名稱。 預設為 NIST P-256 橢圓曲線。

key_operations
list[KeyOperationstr] 或 None

允許的金鑰作業

hardware_protected
boolNone

是否應該在硬體安全性模組中建立金鑰。 預設值為 False

enabled
boolNone

金鑰是否已啟用以供使用。

tags
dict[str, str] 或 None

以機碼/值組形式的應用程式特定中繼資料。

not_before
datetimeNone

不在 UTC 的金鑰日期之前

expires_on
datetimeNone

以 UTC 表示金鑰的到期日

exportable
boolNone

是否可以匯出私密金鑰。

release_policy
KeyReleasePolicyNone

可匯出金鑰的原則規則。

傳回

已建立的金鑰

傳回類型

例外狀況

create_key

建立金鑰,或者,如果 name 已在使用中,請建立新版的金鑰。

需要金鑰/建立許可權。

create_key(name: str, key_type: str | KeyType, **kwargs) -> KeyVaultKey

參數

name
str
必要

新索引鍵的名稱。

key_type
KeyTypestr
必要

要建立的索引鍵類型

size
intNone

以位為單位的金鑰大小。 僅適用于 RSA 和對稱金鑰。 請考慮改用 create_rsa_keycreate_oct_key

curve
KeyCurveNamestrNone

橢圓曲線名稱。 僅適用于橢圓曲線索引鍵。 預設為 NIST P-256 橢圓曲線。 若要建立橢圓曲線索引鍵,請考慮改用 create_ec_key

public_exponent
intNone

要使用的 RSA 公用指數。 僅適用于在受控 HSM 中建立的 RSA 金鑰。

key_operations
list[KeyOperationstr] 或 None

允許的金鑰作業

enabled
boolNone

金鑰是否已啟用以供使用。

tags
dict[str, str] 或 None

以機碼/值組形式的應用程式特定中繼資料。

not_before
datetimeNone

不在 UTC 的金鑰日期之前

expires_on
datetimeNone

以 UTC 表示金鑰的到期日

exportable
boolNone

是否可以匯出私密金鑰。

release_policy
KeyReleasePolicyNone

可匯出金鑰的原則規則。

傳回

已建立的金鑰

傳回類型

例外狀況

create_oct_key

建立新的八位序列 (對稱) 金鑰,如果 name 正在使用中,請建立新版本的金鑰。

需要金鑰/建立權限。

create_oct_key(name: str, **kwargs) -> KeyVaultKey

參數

name
str
必要

新索引鍵的名稱。

size
intNone

以位為單位的金鑰大小,例如 128、192 或 256。

key_operations
list[KeyOperationstr] 或 None

允許的金鑰作業。

hardware_protected
boolNone

是否應該在硬體安全性模組中建立金鑰。 預設值為 False

enabled
boolNone

金鑰是否已啟用以供使用。

tags
dict[str, str] 或 None

以機碼/值組形式的應用程式特定中繼資料。

not_before
datetimeNone

不在 UTC 的金鑰日期之前

expires_on
datetimeNone

以 UTC 表示金鑰的到期日

exportable
boolNone

是否可以匯出金鑰。

release_policy
KeyReleasePolicyNone

可匯出金鑰的原則規則。

傳回

已建立的金鑰

傳回類型

例外狀況

create_rsa_key

建立新的 RSA 金鑰;如果 name 已在使用中,請建立新版的金鑰

需要金鑰/建立權限。

create_rsa_key(name: str, **kwargs) -> KeyVaultKey

參數

name
str
必要

新索引鍵的名稱。

size
intNone

以位為單位的金鑰大小,例如 2048、3072 或 4096。

public_exponent
intNone

要使用的 RSA 公用指數。 僅適用于在受控 HSM 中建立的 RSA 金鑰。

hardware_protected
boolNone

是否應該在硬體安全性模組中建立金鑰。 預設值為 False

key_operations
list[KeyOperationstr] 或 None

允許的金鑰作業

enabled
boolNone

金鑰是否已啟用以供使用。

tags
dict[str, str] 或 None

以機碼/值組形式的應用程式特定中繼資料。

not_before
datetimeNone

不在 UTC 的金鑰日期之前

expires_on
datetimeNone

以 UTC 表示金鑰的到期日

exportable
boolNone

是否可以匯出私密金鑰。

release_policy
KeyReleasePolicyNone

可匯出金鑰的原則規則。

傳回

已建立的金鑰

傳回類型

例外狀況

get_cryptography_client

CryptographyClient取得指定索引鍵的 。

get_cryptography_client(key_name: str, **kwargs) -> CryptographyClient

參數

key_name
str
必要

用來執行密碼編譯作業的金鑰名稱。

key_version
str

用來執行密碼編譯作業的選擇性金鑰版本。

傳回

CryptographyClient 使用與這個 KeyClient 相同的選項、認證和 HTTP 用戶端。

傳回類型

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

get_deleted_key

取得已刪除的金鑰。 只能在已啟用虛刪除的保存庫中進行。

需要金鑰/取得許可權。

get_deleted_key(name: str, **kwargs) -> DeletedKey

參數

name
str
必要

金鑰的名稱

傳回

已刪除的金鑰

傳回類型

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

get_key

取得金鑰的屬性,如果是非對稱金鑰,則為其公開資料。

需要金鑰/取得許可權。

get_key(name: str, version: str | None = None, **kwargs) -> KeyVaultKey

參數

name
str
必要

要取得的金鑰名稱。

version
strNone
必要

(選擇性) 要取得的特定金鑰版本。 如果未指定,則取得最新版的金鑰。

傳回類型

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

get_key_rotation_policy

取得金鑰保存庫金鑰的輪替原則。

get_key_rotation_policy(key_name: str, **kwargs) -> KeyRotationPolicy

參數

key_name
str
必要

索引鍵名稱。

傳回

金鑰輪替原則。

傳回類型

例外狀況

*azure.core.exceptions.HttpResponseError*

get_random_bytes

從受控 HSM 取得要求的隨機位元組數目。

get_random_bytes(count: int, **kwargs) -> bytes

參數

count
int
必要

要求的隨機位元組數目。

傳回

隨機位元組。

傳回類型

例外狀況

如果要求少於一個隨機位元組,則為

針對其他錯誤

import_key

匯入外部建立的金鑰。

需要金鑰/匯入許可權。 如果 name 已在使用中,金鑰將會匯入為新版本。

import_key(name: str, key: JsonWebKey, **kwargs) -> KeyVaultKey

參數

name
str
必要

匯入金鑰的名稱

key
JsonWebKey
必要

要匯入的 JSON Web 金鑰

hardware_protected
boolNone

金鑰是否應受到硬體安全性模組的支援

enabled
boolNone

金鑰是否已啟用以供使用。

tags
dict[str, str] 或 None

以機碼/值組形式的應用程式特定中繼資料。

not_before
datetimeNone

不在 UTC 的金鑰日期之前

expires_on
datetimeNone

以 UTC 表示金鑰的到期日

exportable
boolNone

是否可以匯出私密金鑰。

release_policy
KeyReleasePolicyNone

可匯出金鑰的原則規則。

傳回

匯入的金鑰

傳回類型

例外狀況

list_deleted_keys

列出所有已刪除的金鑰,包括每個的公用部分。 只能在已啟用虛刪除的保存庫中進行。

需要金鑰/清單許可權。

list_deleted_keys(**kwargs) -> ItemPaged[DeletedKey]

傳回

已刪除金鑰的反覆運算器

傳回類型

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

list_properties_of_key_versions

列出金鑰版本的識別碼和屬性。

需要金鑰/清單許可權。

list_properties_of_key_versions(name: str, **kwargs) -> ItemPaged[KeyProperties]

參數

name
str
必要

金鑰的名稱

傳回

金鑰的反覆運算器,不含其密碼編譯資料

傳回類型

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

list_properties_of_keys

列出保存庫中所有金鑰的識別碼和屬性。

需要金鑰/清單許可權。

list_properties_of_keys(**kwargs) -> ItemPaged[KeyProperties]

傳回

金鑰反覆運算器,不含其密碼編譯資料或版本資訊

傳回類型

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

purge_deleted_key

永久刪除已刪除的金鑰。 只有在已啟用虛刪除的保存庫中才可行。

執行無法復原的指定金鑰刪除,而無法復原。 如果 recovery_level 未指定 「可清除」,則無法使用此作業。 只有在清除索引 scheduled_purge_date 鍵之前,才需要這個方法。

需要金鑰/清除許可權。

purge_deleted_key(name: str, **kwargs) -> None

參數

name
str
必要

要清除的已刪除金鑰名稱

傳回

例外狀況

範例


   # if the vault has soft-delete enabled, purge permanently deletes a deleted key
   # (with soft-delete disabled, begin_delete_key is permanent)
   key_client.purge_deleted_key("key-name")

release_key

釋放金鑰。

發行金鑰作業適用于所有金鑰類型。 目標金鑰必須標示為可匯出。 此作業需要金鑰/發行許可權。

release_key(name: str, target_attestation_token: str, **kwargs) -> ReleaseKeyResult

參數

name
str
必要

要取得的金鑰名稱。

target_attestation_token
str
必要

金鑰發行目標的證明判斷提示。

version
strNone

要發行的特定金鑰版本。 如果未指定,則會發行最新版本。

algorithm
strKeyExportEncryptionAlgorithmNone

用來保護已發行金鑰資料的加密演算法。

nonce
strNone

用戶端提供的 nonce 以保持最新狀態。

傳回

金鑰發行的結果。

傳回類型

例外狀況

restore_key_backup

將金鑰備份還原至保存庫。

需要金鑰/還原許可權。

這會匯入金鑰的所有版本,其中包含其名稱、屬性和存取控制原則。 如果金鑰的名稱已在使用中,還原它將會失敗。 此外,目標保存庫必須擁有與來源保存庫相同的 Microsoft Azure 訂用帳戶。

restore_key_backup(backup: bytes, **kwargs) -> KeyVaultKey

參數

backup
bytes
必要

所傳回的金鑰備份 backup_key

傳回

還原的金鑰

傳回類型

例外狀況

如果備份金鑰的名稱已在使用中,則為

針對其他錯誤

rotate_key

藉由產生新版本的金鑰,根據金鑰原則輪替金鑰。

此作業需要金鑰/輪替許可權。

rotate_key(name: str, **kwargs) -> KeyVaultKey

參數

name
str
必要

要輪替的金鑰名稱。

傳回

新版的輪替金鑰。

傳回類型

例外狀況

send_request

使用用戶端的現有管線執行網路要求。

要求 URL 可以相對於保存庫 URL。 除非另有指定,否則用於要求的服務 API 版本與用戶端的版本相同。 如果回應為錯誤,則這個方法不會引發;若要引發例外狀況,請在傳回的回應物件上呼叫 raise_for_status () 。 如需如何使用此方法傳送自訂要求的詳細資訊,請參閱 https://aka.ms/azsdk/dpcodegen/python/send_request

send_request(request: HttpRequest, *, stream: bool = False, **kwargs) -> HttpResponse

參數

request
HttpRequest
必要

您想要進行的網路要求。

stream
bool

是否要串流回應承載。 預設為 False。

傳回

網路呼叫的回應。 不會對回應執行錯誤處理。

傳回類型

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

update_key_properties

變更金鑰的屬性, (不是其密碼編譯資料) 。

需要金鑰/更新許可權。

update_key_properties(name: str, version: str | None = None, **kwargs) -> KeyVaultKey

參數

name
str
必要

要更新的金鑰名稱

version
strNone
必要

(選擇性) 要更新的金鑰版本。 如果未指定,則會更新最新版本。

key_operations
list[KeyOperationstr] 或 None

允許的金鑰作業

enabled
boolNone

金鑰是否已啟用以供使用。

tags
dict[str, str] 或 None

以機碼/值組形式的應用程式特定中繼資料。

not_before
datetimeNone

不在 UTC 的金鑰日期之前

expires_on
datetimeNone

以 UTC 表示金鑰的到期日

release_policy
KeyReleasePolicyNone

可匯出金鑰的原則規則。

傳回

更新的金鑰

傳回類型

例外狀況

如果索引鍵不存在,則為

針對其他錯誤

update_key_rotation_policy

更新金鑰保存庫金鑰的輪替原則。

此作業需要金鑰/更新許可權。

update_key_rotation_policy(key_name: str, policy: KeyRotationPolicy, **kwargs) -> KeyRotationPolicy

參數

key_name
str
必要

指定保存庫中金鑰的名稱。

policy
KeyRotationPolicy
必要

金鑰的新輪替原則。

lifetime_actions
list[KeyRotationLifetimeAction]

金鑰存留期期間金鑰保存庫執行的動作。 這會覆寫所提供 policy 的存留期動作。

expires_in
str

將在新金鑰版本上套用的原則到期時間,定義為 ISO 8601 持續時間。 例如:90 天是 「P90D」,3 個月是 「P3M」,而 48 小時是 「PT48H」。 如需 ISO 8601 持續時間的詳細資訊,請參閱 Wikipedia 。 這會覆寫所提供 policy 的到期時間。

傳回

更新的輪替原則。

傳回類型

例外狀況

屬性

vault_url