Partilhar via

QueueServiceClient Classe

  • Referência

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

Este cliente fornece operações para obter e configurar as propriedades da conta, bem como listar, criar e eliminar filas na conta. Para operações relacionadas com uma fila específica, um cliente para esta entidade pode ser obtido com 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
Necessário

O URL para o ponto final de serviço de fila. Quaisquer outras entidades incluídas no caminho do URL (por exemplo, fila) serão eliminadas. Opcionalmente, este URL pode ser autenticado com um token de SAS.

credential
valor predefinido: None

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

  • exceto no caso do AzureSasCredential, em que os tokens SAS em conflito gerarão um ValueError. Se utilizar uma instância do AzureNamedKeyCredential, "name" deve ser o nome da conta de armazenamento e "chave" deve ser a chave da conta de armazenamento.
api_version
str

A versão da API de Armazenamento a utilizar para pedidos. O valor predefinido é a versão de serviço mais recente compatível com o SDK atual. Definir para uma versão mais antiga pode resultar numa compatibilidade de funcionalidades reduzida.

secondary_hostname
str

O nome do anfitrião do ponto final secundário.

audience
str

A audiência a utilizar ao pedir tokens para autenticação do Azure Active Directory. Só tem um efeito quando a credencial é do tipo TokenCredential. O valor pode ser https://storage.azure.com/ (predefinição) ou https://.queue.core.windows.net.

Exemplos

Criar o QueueServiceClient com um URL e credencial de conta.


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

Criar 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

Este método consiste em fechar os sockets abertos pelo cliente. Não é necessário utilizá-lo ao utilizar com um gestor de contexto.
create_queue

Cria uma nova fila na conta especificada.

Se já existir uma fila com o mesmo nome, a operação falhará. Devolve um cliente com o qual pode interagir com a fila criada recentemente.
delete_queue

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

Quando uma fila é eliminada com êxito, esta é imediatamente marcada para eliminação e já não está acessível aos clientes. A fila é posteriormente removida do serviço Fila durante a recolha de lixo.

Tenha em atenção que a eliminação de uma fila poderá demorar, pelo menos, 40 segundos a concluir. Se for tentada uma operação contra a fila enquanto esta estava a ser eliminada, será lançada uma <xref:azure.storage.queue.aio.HttpResponseError> .
from_connection_string

Crie QueueServiceClient a partir de uma Cadeia de Ligação.
get_queue_client

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

A fila ainda não precisa de existir.
get_service_properties

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

Obtém estatísticas relacionadas com a replicação do serviço Fila.

Só está disponível quando a replicação georredundante de acesso de leitura está ativada para a conta de armazenamento.

Com a replicação georredundante, o Armazenamento do Azure mantém os seus dados duráveis em duas localizações. Em ambas as localizações, o Armazenamento do Azure mantém constantemente múltiplas réplicas em bom estado de funcionamento dos seus dados. A localização onde lê, cria, atualiza ou elimina dados é a localização da conta de armazenamento principal. A localização primária existe na região que escolher no momento em que cria uma conta através do portal clássico do Azure Management do Azure, por exemplo, E.U.A. Centro-Norte. A localização para a qual os seus dados são replicados é a localização secundária. A localização secundária é determinada automaticamente com base na localização da localização primária; é num segundo datacenter que reside na mesma região que a localização primária. O acesso só de leitura está disponível a partir da localização secundária, se a replicação georredundante de acesso de leitura estiver ativada para a sua conta de armazenamento.
list_queues

Devolve um gerador para listar as filas na conta especificada.

O gerador seguirá preguiçosamente os tokens de continuação devolvidos pelo serviço e parará quando todas as filas tiverem sido devolvidas.
set_service_properties

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

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

close

Este método consiste em fechar os sockets abertos pelo cliente. Não é necessário utilizá-lo ao utilizar com um gestor 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á. Devolve um cliente com o qual pode interagir com a fila criada recentemente.

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

Parâmetros

name
str
Necessário

O nome da fila a criar.

metadata
Dict[str, str]
Necessário

Um ditado com name_value pares para associar à fila como metadados. Exemplo: {'Category': 'test'}

timeout
int

O parâmetro de tempo limite é expresso em segundos.

Devoluções

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

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

Quando uma fila é eliminada com êxito, esta é imediatamente marcada para eliminação e já não está acessível aos clientes. A fila é posteriormente removida do serviço Fila durante a recolha de lixo.

Tenha em atenção que a eliminação de uma fila poderá demorar, pelo menos, 40 segundos a concluir. Se for tentada uma operação contra a fila enquanto esta estava a ser eliminada, será lançada uma <xref:azure.storage.queue.aio.HttpResponseError> .

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

Parâmetros

queue
str ou QueueProperties
Necessário

A fila a eliminar. Este pode ser o nome da fila ou uma instância de QueueProperties.

timeout
int

O parâmetro de tempo limite é expresso em segundos.

Tipo de retorno

None

Exemplos

Elimine uma fila no serviço.


   await queue_service.delete_queue("myqueue1")

from_connection_string

Crie QueueServiceClient a partir de uma Cadeia de Ligaçã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
Necessário

Uma cadeia de ligação para uma conta de Armazenamento do Azure.

credential
valor predefinido: None

As credenciais com as quais se autenticar. Isto é opcional se o URL da conta já tiver um token de SAS ou o cadeia de ligação já tiver valores de chave de acesso partilhados. O valor pode ser uma cadeia de token de SAS, uma instância de uma AzureSasCredential ou AzureNamedKeyCredential a partir de azure.core.credentials, uma chave de acesso partilhada de conta ou uma instância de uma classe TokenCredentials a partir de azure.identity. As credenciais aqui fornecidas terão precedência sobre as das cadeia de ligação. Se utilizar uma instância do AzureNamedKeyCredential, "name" deve ser o nome da conta de armazenamento e "chave" deve ser a chave da conta de armazenamento.

Devoluções

Um cliente de serviço fila.

Tipo de retorno

QueueClient

Exemplos

Criar o QueueServiceClient com um cadeia de ligaçã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 de existir.

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

Parâmetros

queue
str ou QueueProperties
Necessário

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

Devoluções

Um QueueClient objeto.

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 o Azure Análise de Armazenamento.

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

Parâmetros

timeout
int

O parâmetro de tempo limite é expresso em segundos.

Devoluções

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

Tipo de retorno

Dict[str, Any]

Exemplos

Obter propriedades do serviço de fila.


   properties = await queue_service.get_service_properties()

get_service_stats

Obtém estatísticas relacionadas com a replicação do serviço Fila.

Só está disponível quando a replicação georredundante de acesso de leitura está ativada para a conta de armazenamento.

Com a replicação georredundante, o Armazenamento do Azure mantém os seus dados duráveis em duas localizações. Em ambas as localizações, o Armazenamento do Azure mantém constantemente múltiplas réplicas em bom estado de funcionamento dos seus dados. A localização onde lê, cria, atualiza ou elimina dados é a localização da conta de armazenamento principal. A localização primária existe na região que escolher no momento em que cria uma conta através do portal clássico do Azure Management do Azure, por exemplo, E.U.A. Centro-Norte. A localização para a qual os seus dados são replicados é a localização secundária. A localização secundária é determinada automaticamente com base na localização da localização primária; é num segundo datacenter que reside na mesma região que a localização primária. O acesso só de leitura está disponível a partir da localização secundária, se a replicação georredundante de acesso de leitura estiver ativada para a sua conta de armazenamento.

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

Parâmetros

timeout
int

O parâmetro de tempo limite é expresso em segundos.

Devoluções

As estatísticas do serviço de fila.

Tipo de retorno

Dict[str, Any]

list_queues

Devolve um gerador para listar as filas na conta especificada.

O gerador seguirá preguiçosamente os tokens de continuação devolvidos pelo serviço e parará quando todas as filas tiverem sido devolvidas.

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

Parâmetros

name_starts_with
str
Necessário

Filtra os resultados para devolver apenas filas cujos nomes começam com o prefixo especificado.

include_metadata
bool
Necessário

Especifica que os metadados da fila são devolvidos na resposta.

results_per_page
int

O número máximo de nomes de filas a obter por chamada à API. Se o pedido não especificar, o servidor devolverá até 5000 itens.

timeout
int

Define o tempo limite do lado do servidor para a operação em segundos. Para obter mais detalhes, veja https://learn.microsoft.com/en-us/rest/api/storageservices/setting-timeouts-for-queue-service-operations. Este valor não é monitorizado nem validado no cliente. Para configurar tempos limite de rede do lado do cliente, veja aqui. Esta 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.

Devoluções

Uma 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 Fila de uma conta de armazenamento, incluindo o Azure Análise de Armazenamento.

Se um elemento (por exemplo, analytics_logging) for deixado como Nenhum, as definiçõ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
Necessário

Agrupa as definições de Registo do Azure Analytics.

hour_metrics
Metrics
Necessário

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

minute_metrics
Metrics
Necessário

As definições de métricas de minutos fornecem estatísticas de pedidos para cada minuto para filas.

cors
Optional[List(CorsRule)]
Necessário

Pode incluir até cinco elementos CorsRule na lista. Se for especificada uma lista vazia, todas as regras CORS serão eliminadas e o CORS será desativado para o serviço.

timeout
int

O parâmetro de tempo limite é expresso em segundos.

Exemplos

Definir 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 utilizada para pedidos.

Tipo de retorno

str

location_mode

O modo de localização que o cliente está a utilizar atualmente.

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

Tipo de retorno

str

primary_endpoint

O URL do ponto final primário completo.

Tipo de retorno

str

primary_hostname

O nome do anfitrião do ponto final primário.

Tipo de retorno

str

secondary_endpoint

O URL completo do ponto final secundário, se configurado.

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

Tipo de retorno

str

Exceções

ValueError

secondary_hostname

O nome do anfitrião do ponto final secundário.

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

Tipo de retorno

Optional[str]

url

O URL de ponto final completo para esta entidade, incluindo o token de SAS, se utilizado.

Este pode ser o ponto final principal ou o ponto final secundário, dependendo do atual location_mode. :returns: o URL de ponto final completo para esta entidade, incluindo o token SAS, se utilizado. :rtype: str