Compartilhar via

QueueServiceClient Classe

  • Referência

Um cliente para interagir com o Serviço de Fila no nível da conta.

Esse cliente fornece operações para recuperar e configurar as propriedades da conta, bem como listar, criar e excluir filas dentro da conta. Para operações relacionadas a uma fila específica, um cliente para essa entidade pode ser recuperado usando a get_queue_client função .

Herança
azure.storage.queue._shared.base_client_async.AsyncStorageAccountHostsMixin
QueueServiceClient
azure.storage.queue._shared.base_client.StorageAccountHostsMixin
QueueServiceClient
azure.storage.queue._encryption.StorageEncryptionMixin
QueueServiceClient

Construtor

QueueServiceClient(account_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | AsyncTokenCredential | None = None, **kwargs: Any)

Parâmetros

account_url
str
Obrigatório

A URL para o ponto de extremidade de serviço de fila. Todas as outras entidades incluídas no caminho da URL (por exemplo, fila) serão descartadas. Essa URL pode ser autenticada opcionalmente com um token SAS.

credential
valor padrão: None

As credenciais com as quais autenticar. Isso será opcional se a URL da conta já tiver um token SAS. O valor pode ser uma cadeia de caracteres de token SAS, uma instância de um AzureSasCredential ou AzureNamedKeyCredential de azure.core.credentials, uma chave de acesso compartilhado de conta ou uma instância de uma classe TokenCredentials de azure.identity. Se o URI do recurso já contiver um token SAS, isso será ignorado em favor de uma credencial explícita

  • exceto no caso de AzureSasCredential, em que os tokens SAS conflitantes gerarão um ValueError. Se estiver usando uma instância de AzureNamedKeyCredential, "name" deverá ser o nome da conta de armazenamento e "key" deverá ser a chave da conta de armazenamento.
api_version
str

A versão da API de Armazenamento a ser usada para solicitações. O valor padrão é a versão de serviço mais recente compatível com o SDK atual. A configuração para uma versão mais antiga pode resultar em redução da compatibilidade de recursos.

secondary_hostname
str

O nome do host do ponto de extremidade secundário.

audience
str

O público-alvo a ser usado ao solicitar tokens para autenticação do Azure Active Directory. Só tem efeito quando a credencial é do tipo TokenCredential. O valor pode ser https://storage.azure.com/ (padrão) ou https://.queue.core.windows.net.

Exemplos

Criando o QueueServiceClient com uma url de conta e uma credencial.


   from azure.storage.queue.aio import QueueServiceClient
   queue_service = QueueServiceClient(account_url=self.account_url, credential=self.access_key)

Criando o QueueServiceClient com credenciais de Identidade do Azure.


   # Get a token credential for authentication
   from azure.identity.aio import ClientSecretCredential
   token_credential = ClientSecretCredential(
       self.active_directory_tenant_id,
       self.active_directory_application_id,
       self.active_directory_application_secret
   )

   # Instantiate a QueueServiceClient using a token credential
   from azure.storage.queue.aio import QueueServiceClient
   queue_service = QueueServiceClient(account_url=self.account_url, credential=token_credential)

Métodos

close

Esse método é para fechar os soquetes abertos pelo cliente. Ele não precisa ser usado ao usar com um gerenciador de contexto.
create_queue

Cria uma nova fila na conta especificada.

Se já existir uma fila com o mesmo nome, a operação falhará. Retorna um cliente com o qual interagir com a fila recém-criada.
delete_queue

Exclui a fila especificada e todas as mensagens que ela contém.

Quando uma fila é excluída com êxito, ela é marcada imediatamente para exclusão e não está mais acessível aos clientes. A fila é removida posteriormente do serviço Fila durante a coleta de lixo.

Observe que a exclusão de uma fila provavelmente levará pelo menos 40 segundos para ser concluída. Se uma operação for tentada na fila enquanto ela estava sendo excluída, uma <xref:azure.storage.queue.aio.HttpResponseError> será lançada.
from_connection_string

Crie QueueServiceClient a partir de uma cadeia de conexão.
get_queue_client

Faça com que um cliente interaja com a fila especificada.

A fila ainda não precisa existir.
get_service_properties

Obtém as propriedades do serviço Fila de uma conta de armazenamento, incluindo Análise de Armazenamento do Azure.
get_service_stats

Recupera as estatísticas relacionadas à replicação do serviço Fila.

Ela só estará disponível quando a replicação com redundância geográfica de acesso de leitura estiver habilitada para a conta de armazenamento.

Com a replicação georredundante, o Armazenamento do Azure mantém seus dados duráveis em dois locais. Em ambos os locais, o Armazenamento do Azure mantém constantemente várias réplicas íntegras de seus dados. O local onde você lê, cria, atualiza ou exclui dados é o local da conta de armazenamento principal. O local principal existe na região escolhida no momento em que você cria uma conta por meio do Portal Clássico do Azure de Gerenciamento do Azure, por exemplo, Centro-Norte dos EUA. O local no qual seus dados são replicados é o local secundário. O local secundário é determinado automaticamente com base no local principal; ele está em um segundo data center que reside na mesma região que o local principal. O acesso somente leitura está disponível no local secundário se a replicação georredundante de acesso de leitura está habilitada para sua conta de armazenamento.
list_queues

Retorna um gerador para listar as filas na conta especificada.

O gerador seguirá lentamente os tokens de continuação retornados pelo serviço e será interrompido quando todas as filas forem retornadas.
set_service_properties

Define as propriedades do serviço Queue de uma conta de armazenamento, incluindo Análise de Armazenamento do Azure.

Se um elemento (por exemplo, analytics_logging) for deixado como Nenhum, as configurações existentes no serviço para essa funcionalidade serão preservadas.

close

Esse método é para fechar os soquetes abertos pelo cliente. Ele não precisa ser usado ao usar com um gerenciador de contexto.

async close()

create_queue

Cria uma nova fila na conta especificada.

Se já existir uma fila com o mesmo nome, a operação falhará. Retorna um cliente com o qual interagir com a fila recém-criada.

async create_queue(name: str, metadata: Dict[str, str] | None = None, **kwargs: Any) -> QueueClient

Parâmetros

name
str
Obrigatório

O nome da fila a ser criada.

metadata
Dict[str, str]
Obrigatório

Um dict com name_value pares a serem associados à fila como metadados. Exemplo: {'Category': 'test'}

timeout
int

O parâmetro timeout é expresso em segundos.

Retornos

Um QueueClient para a Fila recém-criada.

Tipo de retorno

QueueClient

Exemplos

Crie uma fila no serviço.


   await queue_service.create_queue("myqueue1")

delete_queue

Exclui a fila especificada e todas as mensagens que ela contém.

Quando uma fila é excluída com êxito, ela é marcada imediatamente para exclusão e não está mais acessível aos clientes. A fila é removida posteriormente do serviço Fila durante a coleta de lixo.

Observe que a exclusão de uma fila provavelmente levará pelo menos 40 segundos para ser concluída. Se uma operação for tentada na fila enquanto ela estava sendo excluída, uma <xref:azure.storage.queue.aio.HttpResponseError> será lançada.

async delete_queue(queue: QueueProperties | str, **kwargs: Any) -> None

Parâmetros

queue
str ou QueueProperties
Obrigatório

A fila a ser excluída. Pode ser o nome da fila ou uma instância de QueueProperties.

timeout
int

O parâmetro timeout é expresso em segundos.

Tipo de retorno

None

Exemplos

Exclua uma fila no serviço.


   await queue_service.delete_queue("myqueue1")

from_connection_string

Crie QueueServiceClient a partir de uma cadeia de conexão.

from_connection_string(conn_str: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | AsyncTokenCredential | None = None, **kwargs: Any) -> Self

Parâmetros

conn_str
str
Obrigatório

Um cadeia de conexão para uma conta de Armazenamento do Azure.

credential
valor padrão: None

As credenciais com as quais autenticar. Isso é opcional se a URL da conta já tiver um token SAS ou se o cadeia de conexão já tiver valores de chave de acesso compartilhados. O valor pode ser uma cadeia de caracteres de token SAS, uma instância de um AzureSasCredential ou AzureNamedKeyCredential de azure.core.credentials, uma chave de acesso compartilhado de conta ou uma instância de uma classe TokenCredentials de azure.identity. As credenciais fornecidas aqui terão precedência sobre as do cadeia de conexão. Se estiver usando uma instância de AzureNamedKeyCredential, "name" deverá ser o nome da conta de armazenamento e "key" deverá ser a chave da conta de armazenamento.

Retornos

Um cliente do serviço Fila.

Tipo de retorno

QueueClient

Exemplos

Criando o QueueServiceClient com um cadeia de conexão.


   from azure.storage.queue import QueueServiceClient
   queue_service = QueueServiceClient.from_connection_string(conn_str=self.connection_string)

get_queue_client

Faça com que um cliente interaja com a fila especificada.

A fila ainda não precisa existir.

get_queue_client(queue: QueueProperties | str, **kwargs: Any) -> QueueClient

Parâmetros

queue
str ou QueueProperties
Obrigatório

A fila. Pode ser o nome da fila ou uma instância de QueueProperties.

Retornos

Um objeto QueueClient.

Tipo de retorno

QueueClient

Exemplos

Obtenha o cliente da fila.


   # Get the queue client to interact with a specific queue
   queue = queue_service.get_queue_client(queue="myqueue2")

get_service_properties

Obtém as propriedades do serviço Fila de uma conta de armazenamento, incluindo Análise de Armazenamento do Azure.

async get_service_properties(**kwargs: Any) -> Dict[str, Any]

Parâmetros

timeout
int

O parâmetro timeout é expresso em segundos.

Retornos

Um objeto que contém propriedades de serviço de fila, como log de análise, métricas de hora/minuto, regras de cors etc.

Tipo de retorno

Dict[str, Any]

Exemplos

Obtendo propriedades do serviço de fila.


   properties = await queue_service.get_service_properties()

get_service_stats

Recupera as estatísticas relacionadas à replicação do serviço Fila.

Ela só estará disponível quando a replicação com redundância geográfica de acesso de leitura estiver habilitada para a conta de armazenamento.

Com a replicação georredundante, o Armazenamento do Azure mantém seus dados duráveis em dois locais. Em ambos os locais, o Armazenamento do Azure mantém constantemente várias réplicas íntegras de seus dados. O local onde você lê, cria, atualiza ou exclui dados é o local da conta de armazenamento principal. O local principal existe na região escolhida no momento em que você cria uma conta por meio do Portal Clássico do Azure de Gerenciamento do Azure, por exemplo, Centro-Norte dos EUA. O local no qual seus dados são replicados é o local secundário. O local secundário é determinado automaticamente com base no local principal; ele está em um segundo data center que reside na mesma região que o local principal. O acesso somente leitura está disponível no local secundário se a replicação georredundante de acesso de leitura está habilitada para sua conta de armazenamento.

async get_service_stats(**kwargs: Any) -> Dict[str, Any]

Parâmetros

timeout
int

O parâmetro timeout é expresso em segundos.

Retornos

Os status do serviço de fila.

Tipo de retorno

Dict[str, Any]

list_queues

Retorna um gerador para listar as filas na conta especificada.

O gerador seguirá lentamente os tokens de continuação retornados pelo serviço e será interrompido quando todas as filas forem retornadas.

list_queues(name_starts_with: str | None = None, include_metadata: bool | None = False, **kwargs: Any) -> AsyncItemPaged

Parâmetros

name_starts_with
str
Obrigatório

Filtra os resultados para retornar somente filas cujos nomes começam com o prefixo especificado.

include_metadata
bool
Obrigatório

Especifica que os metadados da fila sejam retornados na resposta.

results_per_page
int

O número máximo de nomes de fila a serem recuperados por chamada à API. Se a solicitação não especificar, o servidor retornará até 5.000 itens.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais informações, confira https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations. Esse valor não é rastreado ou validado no cliente. Para configurar tempos limite de rede do lado do cliente, consulte aqui. Essa função pode fazer várias chamadas para o serviço, caso em que o valor de tempo limite especificado será aplicado a cada chamada individual.

Retornos

Um iterável (paginação automática) de QueueProperties.

Tipo de retorno

<xref:azure.core.paging.AsyncItemPaged>[QueueProperties]

Exemplos

Listar filas no serviço.


   # List all the queues in the service
   list_queues = queue_service.list_queues()
   async for queue in list_queues:
       print(queue)

   # List the queues in the service that start with the name "my_"
   list_my_queues = queue_service.list_queues(name_starts_with="my_")
   async for queue in list_my_queues:
       print(queue)

set_service_properties

Define as propriedades do serviço Queue de uma conta de armazenamento, incluindo Análise de Armazenamento do Azure.

Se um elemento (por exemplo, analytics_logging) for deixado como Nenhum, as configurações existentes no serviço para essa funcionalidade serão preservadas.

async set_service_properties(analytics_logging: QueueAnalyticsLogging | None = None, hour_metrics: Metrics | None = None, minute_metrics: Metrics | None = None, cors: List[CorsRule] | None = None, **kwargs: Any) -> None

Parâmetros

analytics_logging
QueueAnalyticsLogging
Obrigatório

Agrupa as configurações de Log da Análise do Azure.

hour_metrics
Metrics
Obrigatório

As configurações de métricas de hora fornecem um resumo das estatísticas de solicitação agrupadas pela API em agregações por hora para filas.

minute_metrics
Metrics
Obrigatório

As configurações de métricas de minuto fornecem estatísticas de solicitação para cada minuto para filas.

cors
Optional[List(CorsRule)]
Obrigatório

Você pode incluir até cinco elementos CorsRule na lista. Se uma lista vazia for especificada, todas as regras CORS serão excluídas e o CORS será desabilitado para o serviço.

timeout
int

O parâmetro timeout é expresso em segundos.

Exemplos

Definindo as propriedades do serviço de fila.


   # Create service properties
   from azure.storage.queue import QueueAnalyticsLogging, Metrics, CorsRule, RetentionPolicy

   # Create logging settings
   logging = QueueAnalyticsLogging(read=True, write=True, delete=True, retention_policy=RetentionPolicy(enabled=True, days=5))

   # Create metrics for requests statistics
   hour_metrics = Metrics(enabled=True, include_apis=True, retention_policy=RetentionPolicy(enabled=True, days=5))
   minute_metrics = Metrics(enabled=True, include_apis=True, retention_policy=RetentionPolicy(enabled=True, days=5))

   # Create CORS rules
   cors_rule1 = CorsRule(['www.xyz.com'], ['GET'])
   allowed_origins = ['www.xyz.com', "www.ab.com", "www.bc.com"]
   allowed_methods = ['GET', 'PUT']
   max_age_in_seconds = 500
   exposed_headers = ["x-ms-meta-data*", "x-ms-meta-source*", "x-ms-meta-abc", "x-ms-meta-bcd"]
   allowed_headers = ["x-ms-meta-data*", "x-ms-meta-target*", "x-ms-meta-xyz", "x-ms-meta-foo"]
   cors_rule2 = CorsRule(
       allowed_origins,
       allowed_methods,
       max_age_in_seconds=max_age_in_seconds,
       exposed_headers=exposed_headers,
       allowed_headers=allowed_headers
   )

   cors = [cors_rule1, cors_rule2]

   # Set the service properties
   await queue_service.set_service_properties(logging, hour_metrics, minute_metrics, cors)

Atributos

api_version

A versão da API de Armazenamento usada para solicitações.

Tipo de retorno

str

location_mode

O modo de localização que o cliente está usando no momento.

Por padrão, isso será "primário". As opções incluem "primário" e "secundário".

Tipo de retorno

str

primary_endpoint

A URL completa do ponto de extremidade primário.

Tipo de retorno

str

primary_hostname

O nome do host do ponto de extremidade primário.

Tipo de retorno

str

secondary_endpoint

A URL completa do ponto de extremidade secundário, se configurada.

Se não estiver disponível, um ValueError será gerado. Para especificar explicitamente um nome de host secundário, use o argumento opcional secondary_hostname palavra-chave na instanciação.

Tipo de retorno

str

Exceções

ValueError

secondary_hostname

O nome do host do ponto de extremidade secundário.

Se não estiver disponível, será Nenhum. Para especificar explicitamente um nome de host secundário, use o argumento opcional secondary_hostname palavra-chave na instanciação.

Tipo de retorno

Optional[str]

url

A URL completa do ponto de extremidade para essa entidade, incluindo o token SAS, se usado.

Isso pode ser o ponto de extremidade primário ou o ponto de extremidade secundário, dependendo do atual location_mode. :returns: a URL completa do ponto de extremidade para essa entidade, incluindo o token SAS, se usado. :rtype: str