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 .

Para obter mais configuração opcional, clique aqui.

Herança
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 | TokenCredential | None = None, **kwargs: Any)

Parâmetros

account_url
str
Necessário

O URL para o ponto final de serviço da 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 um 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 uma credencial de conta.


   from azure.storage.queue 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 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 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á-la 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 interagir com a fila recém-criada.
delete_queue

Elimina a fila especificada e quaisquer mensagens que contenha.

Quando uma fila é eliminada com êxito, é imediatamente marcada para eliminação e já não está acessível aos clientes. A fila é posteriormente removida do serviço Fila durante a libertação da memória.

Tenha em atenção que a eliminação de uma fila poderá demorar, pelo menos, 40 segundos a ser concluída. Se for tentada uma operação na fila enquanto esta estava a ser eliminada, será emitida uma <xref:azure.storage.queue.HttpResponseError> .
from_connection_string

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

Obter um cliente para interagir 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 várias réplicas em bom estado de funcionamento dos seus dados. A localização onde lê, cria, atualiza ou elimina dados é a localização principal da conta de armazenamento. 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 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 com 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á lentamente 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 são preservadas.

close

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

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 interagir com a fila recém-criada.

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 pares name_value 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

Criar uma fila no serviço.


   queue_service.create_queue("myqueue1")

delete_queue

Elimina a fila especificada e quaisquer mensagens que contenha.

Quando uma fila é eliminada com êxito, é imediatamente marcada para eliminação e já não está acessível aos clientes. A fila é posteriormente removida do serviço Fila durante a libertação da memória.

Tenha em atenção que a eliminação de uma fila poderá demorar, pelo menos, 40 segundos a ser concluída. Se for tentada uma operação na fila enquanto esta estava a ser eliminada, será emitida uma <xref:azure.storage.queue.HttpResponseError> .

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

Parâmetros

queue
str ou QueueProperties
Necessário

A fila a eliminar. 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

Eliminar uma fila no serviço.


   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 | TokenCredential | None = None, **kwargs: Any) -> Self

Parâmetros

conn_str
str
Necessário

Uma cadeia de ligação a 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 se 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 um 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 credenciais na 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.

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.

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

Obter um cliente para interagir 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. 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 de 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.

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, como o registo de análise, métricas de hora/minuto, regras cors, etc.

Tipo de retorno

Dict[str, Any]

Exemplos

Obter as propriedades do serviço de fila.


   properties = 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 várias réplicas em bom estado de funcionamento dos seus dados. A localização onde lê, cria, atualiza ou elimina dados é a localização principal da conta de armazenamento. 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 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 com acesso de leitura estiver ativada para a sua conta de armazenamento.

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á lentamente 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) -> ItemPaged[QueueProperties]

Parâmetros

name_starts_with
str
Necessário

Filtra os resultados para devolver apenas as 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 é controlado ou 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

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

Tipo de retorno

ItemPaged[QueueProperties]

Exemplos

Listar filas no serviço.


   # List all the queues in the service
   list_queues = queue_service.list_queues()
   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")
   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 são preservadas.

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 do 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 minuto 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
   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á "principal". As opções incluem "principal" e "secundário".

Tipo de retorno

str

primary_endpoint

O URL completo do ponto final primário.

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, 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 primário ou o ponto final secundário, dependendo do atual location_mode. :returns: o URL de ponto final completo para esta entidade, incluindo o token de SAS, se utilizado. :rtype: str