Partilhar via


KeyClient Classe

Uma interface de alto nível para gerir as chaves de um cofre.

Herança
azure.keyvault.keys._shared.client_base.KeyVaultClientBase
KeyClient

Construtor

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

Parâmetros

vault_url
str
Necessário

URL do cofre ao qual o cliente irá aceder. Isto também é chamado de "Nome DNS" do cofre. Deve validar que este URL faz referência a um recurso de Key Vault ou HSM gerido válido. Veja https://aka.ms/azsdk/blog/vault-uri para obter detalhes.

credential
TokenCredential
Necessário

Um objeto que pode fornecer um token de acesso para o cofre, como uma credencial de identity

api_version
ApiVersion

Versão da API de serviço a utilizar. A predefinição é a mais recente.

verify_challenge_resource
bool

A verificação do recurso de desafio de autenticação corresponde ao domínio do Key Vault ou do HSM Gerido. A predefinição é Verdadeiro.

Métodos

backup_key

Crie uma cópia de segurança de uma chave num formulário protegido utilizável apenas pelo Azure Key Vault.

Necessita de chaves/permissão de cópia de segurança.

Destina-se a permitir a cópia de uma chave de um cofre para outro. Ambos os cofres têm de ser propriedade da mesma subscrição do Azure. Além disso, a cópia de segurança/restauro não pode ser efetuada em limites geopolíticos. Por exemplo, uma cópia de segurança de um cofre numa região dos EUA não pode ser restaurada para um cofre numa região da UE.

begin_delete_key

Elimine todas as versões de uma chave e o respetivo material criptográfico.

Requer permissões de chaves/eliminação. Quando este método devolve Key Vault começou a eliminar a chave. A eliminação pode demorar vários segundos num cofre com a eliminação recuperável ativada. Por conseguinte, este método devolve um poller que lhe permite aguardar a conclusão da eliminação.

begin_recover_deleted_key

Recuperar uma chave eliminada para a versão mais recente. Só é possível num cofre com a eliminação recuperável ativada.

Necessita de chaves/permissão de recuperação.

Quando este método devolve Key Vault começou a recuperar a chave. A recuperação pode demorar vários segundos. Por conseguinte, este método devolve um poller que lhe permite aguardar pela conclusão da recuperação. A espera só é necessária quando pretender utilizar a chave recuperada noutra operação imediatamente.

close

Feche os sockets abertos pelo cliente.

Chamar este método é desnecessário ao utilizar o cliente como um gestor de contexto.

create_ec_key

Crie uma nova tecla curva elíptica ou, se name já estiver a ser utilizada, crie uma nova versão da chave.

Requer as chaves/permissão de criação.

create_key

Crie uma chave ou, se name já estiver a ser utilizada, crie uma nova versão da chave.

Requer chaves/permissão de criação.

create_oct_key

Crie uma nova chave de sequência octeto (simétrica) ou, se name estiver a ser utilizada, crie uma nova versão da chave.

Requer as chaves/permissão de criação.

create_rsa_key

Criar uma nova chave RSA ou, se name já estiver a ser utilizada, criar uma nova versão da chave

Requer as chaves/permissão de criação.

get_cryptography_client

Obtém um CryptographyClient para a chave especificada.

get_deleted_key

Obter uma chave eliminada. Só é possível num cofre com a eliminação recuperável ativada.

Requer chaves/obter permissão.

get_key

Obtenha os atributos de uma chave e, se for uma chave assimétrica, o respetivo material público.

Requer chaves/obter permissão.

get_key_rotation_policy

Obtenha a política de rotação de uma chave de Key Vault.

get_random_bytes

Obtenha o número pedido de bytes aleatórios de um HSM gerido.

import_key

Importar uma chave criada externamente.

Requer permissões de importação/chaves. Se name já estiver a ser utilizada, a chave será importada como uma nova versão.

list_deleted_keys

Liste todas as chaves eliminadas, incluindo a parte pública de cada uma. Só é possível num cofre com a eliminação recuperável ativada.

Requer permissões de chaves/lista.

list_properties_of_key_versions

Liste os identificadores e propriedades das versões de uma chave.

Requer permissões de chaves/lista.

list_properties_of_keys

Listar identificadores e propriedades de todas as chaves no cofre.

Requer permissões de chaves/lista.

purge_deleted_key

Elimina permanentemente uma chave eliminada. Só é possível num cofre com a eliminação recuperável ativada.

Efetua uma eliminação irreversível da chave especificada, sem possibilidade de recuperação. A operação não está disponível se o recovery_level não especificar "Purgeable". Este método só é necessário para remover uma chave antes do respetivo scheduled_purge_date.

Requer chaves/permissão de remoção.

release_key

Liberta uma chave.

A operação da chave de lançamento é aplicável a todos os tipos de chaves. A chave de destino tem de ser marcada como exportável. Esta operação requer a permissão de chaves/versão.

restore_key_backup

Restaure uma cópia de segurança de chave para o cofre.

Requer permissões de chaves/restauro.

Esta ação importa todas as versões da chave, com o respetivo nome, atributos e políticas de controlo de acesso. Se o nome da chave já estiver a ser utilizado, o restauro falhará. Além disso, o cofre de destino tem de ser propriedade da mesma subscrição do Microsoft Azure que o cofre de origem.

rotate_key

Rode a chave com base na política de chave ao gerar uma nova versão da chave.

Esta operação requer as chaves/permissões de rotação.

send_request

Executa um pedido de rede com o pipeline existente do cliente.

O URL do pedido pode ser relativo ao URL do cofre. A versão da API de serviço utilizada para o pedido é igual à do cliente, salvo especificação em contrário. Este método não aumenta se a resposta for um erro; para gerar uma exceção, chame raise_for_status() no objeto de resposta devolvido. Para obter mais informações sobre como enviar pedidos personalizados com este método, consulte https://aka.ms/azsdk/dpcodegen/python/send_request.

update_key_properties

Altere as propriedades de uma chave (não o respetivo material criptográfico).

Requer permissões de chaves/atualização.

update_key_rotation_policy

Atualizações a política de rotação de uma chave de Key Vault.

Esta operação requer as chaves/permissão de atualização.

backup_key

Crie uma cópia de segurança de uma chave num formulário protegido utilizável apenas pelo Azure Key Vault.

Necessita de chaves/permissão de cópia de segurança.

Destina-se a permitir a cópia de uma chave de um cofre para outro. Ambos os cofres têm de ser propriedade da mesma subscrição do Azure. Além disso, a cópia de segurança/restauro não pode ser efetuada em limites geopolíticos. Por exemplo, uma cópia de segurança de um cofre numa região dos EUA não pode ser restaurada para um cofre numa região da UE.

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

Parâmetros

name
str
Necessário

O nome da chave para fazer uma cópia de segurança

Tipo de retorno

Exceções

se a chave não existir,

para outros erros

begin_delete_key

Elimine todas as versões de uma chave e o respetivo material criptográfico.

Requer permissões de chaves/eliminação. Quando este método devolve Key Vault começou a eliminar a chave. A eliminação pode demorar vários segundos num cofre com a eliminação recuperável ativada. Por conseguinte, este método devolve um poller que lhe permite aguardar a conclusão da eliminação.

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

Parâmetros

name
str
Necessário

O nome da chave a eliminar.

Devoluções

Um poller para a operação eliminar chave. O método de resultado do poller devolve o DeletedKey sem aguardar que a eliminação seja concluída. Se o cofre tiver a eliminação recuperável ativada e quiser eliminar permanentemente a chave com purge_deleted_key, chame primeiro o método de espera do poller. Irá bloquear até que a eliminação esteja concluída. O método de espera requer chaves/permissão de obtenção.

Tipo de retorno

Exceções

se a chave não existir,

para outros erros

begin_recover_deleted_key

Recuperar uma chave eliminada para a versão mais recente. Só é possível num cofre com a eliminação recuperável ativada.

Necessita de chaves/permissão de recuperação.

Quando este método devolve Key Vault começou a recuperar a chave. A recuperação pode demorar vários segundos. Por conseguinte, este método devolve um poller que lhe permite aguardar pela conclusão da recuperação. A espera só é necessária quando pretender utilizar a chave recuperada noutra operação imediatamente.

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

Parâmetros

name
str
Necessário

O nome da chave eliminada a recuperar

Devoluções

Um poller para a operação de recuperação. O método de resultado do poller devolve o recuperado KeyVaultKey sem esperar que a recuperação seja concluída. Se quiser utilizar a chave recuperada imediatamente, chame o método de espera do poller, que bloqueia até a chave estar pronta para ser utilizada. O método de espera requer chaves/permissão de obtenção.

Tipo de retorno

Exceções

close

Feche os sockets abertos pelo cliente.

Chamar este método é desnecessário ao utilizar o cliente como um gestor de contexto.

close() -> None

Exceções

se a chave não existir,

para outros erros

create_ec_key

Crie uma nova tecla curva elíptica ou, se name já estiver a ser utilizada, crie uma nova versão da chave.

Requer as chaves/permissão de criação.

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

Parâmetros

name
str
Necessário

O nome da nova chave.

curve
KeyCurveName ou str ou None

Nome da curva elíptica. A predefinição é a curva elíptica NIST P-256.

key_operations
list[KeyOperation ou str] ou None

Operações de chaves permitidas

hardware_protected
bool ou None

Se a chave deve ser criada num módulo de segurança de hardware. A predefinição é False.

enabled
bool ou None

Se a chave está ativada para utilização.

tags
dict[str, str] ou None

Metadados específicos da aplicação sob a forma de pares chave-valor.

not_before
datetime ou None

Não antes da data da chave em UTC

expires_on
datetime ou None

Data de expiração da chave em UTC

exportable
bool ou None

Se a chave privada pode ser exportada.

release_policy
KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Devoluções

A chave criada

Tipo de retorno

Exceções

create_key

Crie uma chave ou, se name já estiver a ser utilizada, crie uma nova versão da chave.

Requer chaves/permissão de criação.

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

Parâmetros

name
str
Necessário

O nome da nova chave.

key_type
KeyType ou str
Necessário

O tipo de chave a criar

size
int ou None

Tamanho da chave em bits. Aplica-se apenas a RSA e chaves simétricas. Considere utilizar create_rsa_key ou create_oct_key em alternativa.

curve
KeyCurveName ou str ou None

Nome da curva elíptica. Aplica-se apenas às teclas curvas elípticas. A predefinição é a curva elíptica NIST P-256. Para criar uma chave de curva elíptica, considere utilizar create_ec_key .

public_exponent
int ou None

O expoente público RSA a utilizar. Aplica-se apenas a chaves RSA criadas num HSM Gerido.

key_operations
list[KeyOperation ou str] ou None

Operações de chaves permitidas

enabled
bool ou None

Se a chave está ativada para utilização.

tags
dict[str, str] ou None

Metadados específicos da aplicação sob a forma de pares chave-valor.

not_before
datetime ou None

Não antes da data da chave em UTC

expires_on
datetime ou None

Data de expiração da chave em UTC

exportable
bool ou None

Se a chave privada pode ser exportada.

release_policy
KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Devoluções

A chave criada

Tipo de retorno

Exceções

create_oct_key

Crie uma nova chave de sequência octeto (simétrica) ou, se name estiver a ser utilizada, crie uma nova versão da chave.

Requer as chaves/permissão de criação.

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

Parâmetros

name
str
Necessário

O nome da nova chave.

size
int ou None

Tamanho da chave em bits, por exemplo 128, 192 ou 256.

key_operations
list[KeyOperation ou str] ou None

Operações de chave permitidas.

hardware_protected
bool ou None

Se a chave deve ser criada num módulo de segurança de hardware. A predefinição é False.

enabled
bool ou None

Se a chave está ativada para utilização.

tags
dict[str, str] ou None

Metadados específicos da aplicação sob a forma de pares chave-valor.

not_before
datetime ou None

Não antes da data da chave em UTC

expires_on
datetime ou None

Data de expiração da chave em UTC

exportable
bool ou None

Se a chave pode ser exportada.

release_policy
KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Devoluções

A chave criada

Tipo de retorno

Exceções

create_rsa_key

Criar uma nova chave RSA ou, se name já estiver a ser utilizada, criar uma nova versão da chave

Requer as chaves/permissão de criação.

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

Parâmetros

name
str
Necessário

O nome da nova chave.

size
int ou None

Tamanho da chave em bits, por exemplo 2048, 3072 ou 4096.

public_exponent
int ou None

O expoente público RSA a utilizar. Aplica-se apenas a chaves RSA criadas num HSM Gerido.

hardware_protected
bool ou None

Se a chave deve ser criada num módulo de segurança de hardware. A predefinição é False.

key_operations
list[KeyOperation ou str] ou None

Operações de chaves permitidas

enabled
bool ou None

Se a chave está ativada para utilização.

tags
dict[str, str] ou None

Metadados específicos da aplicação sob a forma de pares chave-valor.

not_before
datetime ou None

Não antes da data da chave em UTC

expires_on
datetime ou None

Data de expiração da chave em UTC

exportable
bool ou None

Se a chave privada pode ser exportada.

release_policy
KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Devoluções

A chave criada

Tipo de retorno

Exceções

get_cryptography_client

Obtém um CryptographyClient para a chave especificada.

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

Parâmetros

key_name
str
Necessário

O nome da chave utilizada para realizar operações criptográficas.

key_version
str

Versão opcional da chave utilizada para realizar operações criptográficas.

Devoluções

Um CryptographyClient com as mesmas opções, credenciais e cliente HTTP que este KeyClient.

Tipo de retorno

Exceções

se a chave não existir,

para outros erros

get_deleted_key

Obter uma chave eliminada. Só é possível num cofre com a eliminação recuperável ativada.

Requer chaves/obter permissão.

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

Parâmetros

name
str
Necessário

O nome da chave

Devoluções

A chave eliminada

Tipo de retorno

Exceções

se a chave não existir,

para outros erros

get_key

Obtenha os atributos de uma chave e, se for uma chave assimétrica, o respetivo material público.

Requer chaves/obter permissão.

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

Parâmetros

name
str
Necessário

O nome da chave a obter.

version
str ou None
Necessário

(opcional) Uma versão específica da chave a obter. Se não for especificado, obtém a versão mais recente da chave.

Tipo de retorno

Exceções

se a chave não existir,

para outros erros

get_key_rotation_policy

Obtenha a política de rotação de uma chave de Key Vault.

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

Parâmetros

key_name
str
Necessário

O nome da chave.

Devoluções

A política de rotação de chaves.

Tipo de retorno

Exceções

*azure.core.exceptions.HttpResponseError*

get_random_bytes

Obtenha o número pedido de bytes aleatórios de um HSM gerido.

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

Parâmetros

count
int
Necessário

O número pedido de bytes aleatórios.

Devoluções

Os bytes aleatórios.

Tipo de retorno

Exceções

se for pedido menos de um byte aleatório,

para outros erros

import_key

Importar uma chave criada externamente.

Requer permissões de importação/chaves. Se name já estiver a ser utilizada, a chave será importada como uma nova versão.

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

Parâmetros

name
str
Necessário

Nome da chave importada

key
JsonWebKey
Necessário

A chave Web JSON a importar

hardware_protected
bool ou None

Se a chave deve ser suportada por um módulo de segurança de hardware

enabled
bool ou None

Se a chave está ativada para utilização.

tags
dict[str, str] ou None

Metadados específicos da aplicação sob a forma de pares chave-valor.

not_before
datetime ou None

Não antes da data da chave em UTC

expires_on
datetime ou None

Data de expiração da chave em UTC

exportable
bool ou None

Se a chave privada pode ser exportada.

release_policy
KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Devoluções

A chave importada

Tipo de retorno

Exceções

list_deleted_keys

Liste todas as chaves eliminadas, incluindo a parte pública de cada uma. Só é possível num cofre com a eliminação recuperável ativada.

Requer permissões de chaves/lista.

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

Devoluções

Um iterador de chaves eliminadas

Tipo de retorno

Exceções

se a chave não existir,

para outros erros

list_properties_of_key_versions

Liste os identificadores e propriedades das versões de uma chave.

Requer permissões de chaves/lista.

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

Parâmetros

name
str
Necessário

O nome da chave

Devoluções

Um iterador de chaves sem o seu material criptográfico

Tipo de retorno

Exceções

se a chave não existir,

para outros erros

list_properties_of_keys

Listar identificadores e propriedades de todas as chaves no cofre.

Requer permissões de chaves/lista.

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

Devoluções

Um iterador de chaves sem o respetivo material criptográfico ou informações de versão

Tipo de retorno

Exceções

se a chave não existir,

para outros erros

purge_deleted_key

Elimina permanentemente uma chave eliminada. Só é possível num cofre com a eliminação recuperável ativada.

Efetua uma eliminação irreversível da chave especificada, sem possibilidade de recuperação. A operação não está disponível se o recovery_level não especificar "Purgeable". Este método só é necessário para remover uma chave antes do respetivo scheduled_purge_date.

Requer chaves/permissão de remoção.

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

Parâmetros

name
str
Necessário

O nome da chave eliminada a remover

Devoluções

Nenhuma

Exceções

Exemplos


   # 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

Liberta uma chave.

A operação da chave de lançamento é aplicável a todos os tipos de chaves. A chave de destino tem de ser marcada como exportável. Esta operação requer a permissão de chaves/versão.

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

Parâmetros

name
str
Necessário

O nome da chave a obter.

target_attestation_token
str
Necessário

A asserção do atestado para o destino da versão da chave.

version
str ou None

Uma versão específica da chave a lançar. Se não for especificado, é lançada a versão mais recente.

algorithm
str ou KeyExportEncryptionAlgorithm ou None

O algoritmo de encriptação a utilizar para proteger o material de chave libertado.

nonce
str ou None

Um nonce fornecido pelo cliente para atualização.

Devoluções

O resultado da versão da chave.

Tipo de retorno

Exceções

restore_key_backup

Restaure uma cópia de segurança de chave para o cofre.

Requer permissões de chaves/restauro.

Esta ação importa todas as versões da chave, com o respetivo nome, atributos e políticas de controlo de acesso. Se o nome da chave já estiver a ser utilizado, o restauro falhará. Além disso, o cofre de destino tem de ser propriedade da mesma subscrição do Microsoft Azure que o cofre de origem.

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

Parâmetros

backup
bytes
Necessário

Uma cópia de segurança de chave, conforme devolvido por backup_key

Devoluções

A chave restaurada

Tipo de retorno

Exceções

se o nome da chave de cópia de segurança já estiver a ser utilizado,

para outros erros

rotate_key

Rode a chave com base na política de chave ao gerar uma nova versão da chave.

Esta operação requer as chaves/permissões de rotação.

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

Parâmetros

name
str
Necessário

O nome da chave a rodar.

Devoluções

A nova versão da chave rodada.

Tipo de retorno

Exceções

send_request

Executa um pedido de rede com o pipeline existente do cliente.

O URL do pedido pode ser relativo ao URL do cofre. A versão da API de serviço utilizada para o pedido é igual à do cliente, salvo especificação em contrário. Este método não aumenta se a resposta for um erro; para gerar uma exceção, chame raise_for_status() no objeto de resposta devolvido. Para obter mais informações sobre como enviar pedidos personalizados com este método, consulte https://aka.ms/azsdk/dpcodegen/python/send_request.

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

Parâmetros

request
HttpRequest
Necessário

O pedido de rede que pretende fazer.

stream
bool

Se o payload de resposta será transmitido em fluxo. Predefinições para Falso.

Devoluções

A resposta da chamada de rede. Não efetua o processamento de erros na resposta.

Tipo de retorno

Exceções

se a chave não existir,

para outros erros

update_key_properties

Altere as propriedades de uma chave (não o respetivo material criptográfico).

Requer permissões de chaves/atualização.

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

Parâmetros

name
str
Necessário

O nome da chave a atualizar

version
str ou None
Necessário

(opcional) A versão da chave a atualizar. Se não for especificado, a versão mais recente é atualizada.

key_operations
list[KeyOperation ou str] ou None

Operações chave permitidas

enabled
bool ou None

Se a chave está ativada para utilização.

tags
dict[str, str] ou None

Metadados específicos da aplicação na forma de pares chave-valor.

not_before
datetime ou None

Não antes da data da chave em UTC

expires_on
datetime ou None

Data de expiração da chave em UTC

release_policy
KeyReleasePolicy ou None

As regras de política sob as quais a chave pode ser exportada.

Devoluções

A chave atualizada

Tipo de retorno

Exceções

se a chave não existir,

para outros erros

update_key_rotation_policy

Atualizações a política de rotação de uma chave de Key Vault.

Esta operação requer as chaves/permissão de atualização.

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

Parâmetros

key_name
str
Necessário

O nome da chave no cofre especificado.

policy
KeyRotationPolicy
Necessário

A nova política de rotação da chave.

lifetime_actions
list[KeyRotationLifetimeAction]

Ações que serão executadas por Key Vault ao longo da duração de uma chave. Esta ação substituirá as ações de duração do fornecido policy.

expires_in
str

O tempo de expiração da política que será aplicada em novas versões de chave, definida como uma duração ISO 8601. Por exemplo: 90 dias é "P90D", 3 meses é "P3M" e 48 horas é "PT48H". Veja Wikipédia para obter mais informações sobre as durações do ISO 8601. Esta ação substituirá o tempo de expiração do fornecido policy.

Devoluções

A política de rotação atualizada.

Tipo de retorno

Exceções

Atributos

vault_url