Listar filas

Artigo
06/27/2023

Essa operação lista todas as filas em uma conta de armazenamento específica.

Solicitação

Você pode construir a solicitação da List Queues seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento.

Método	URI da solicitação	Versão HTTP
`GET`	`https://myaccount.queue.core.windows.net?comp=list`	HTTP/1.1

URI do serviço de armazenamento emulado

Ao fazer uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e a porta do Armazenamento de Filas do Azure como 127.0.0.1:10001, seguido pelo nome da conta de armazenamento emulado.

Método	URI da solicitação	Versão HTTP
`GET`	`http://127.0.0.1:10001/devstoreaccount1?comp=list`	HTTP/1.1

Parâmetros de URI

Você pode especificar os seguintes parâmetros adicionais no URI de solicitação.

Parâmetro	Descrição
`prefix`	Filtra os resultados para retornar apenas filas cujos nomes começam com o prefixo especificado.
`marker`	Um valor de cadeia de caracteres que identifica a parte da lista a ser retornada com a próxima operação na lista. A operação retornará um `NextMarker` elemento dentro do corpo da resposta, se a lista retornada não estiver concluída. Em seguida, você pode usar esse valor como um parâmetro de consulta em uma chamada subsequente para solicitar a próxima parte da lista de filas. O valor do marcador é opaco ao cliente.
`maxresults`	Especifica o número máximo de filas a serem retornadas. Se `maxresults` não for especificado, o servidor retornará até 5.000 itens.
`include=metadata`	Opcional. Inclua esse parâmetro para especificar que os metadados do contêiner são retornados como parte do corpo da resposta. Observe que os metadados solicitados com esse parâmetro devem ser armazenados de acordo com as restrições de nomenclatura impostas pela versão 2009-09-19 do Armazenamento de Filas. A partir dessa versão, todos os nomes de metadados devem aderir às convenções de nomenclatura para identificadores C#.
`timeout`	Opcional. O parâmetro `timeout` é expresso em segundos. Para obter mais informações, consulte Configurando tempos limite para operações de Armazenamento de Filas.

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho da solicitação	Descrição
`Authorization`	Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`x-ms-version`	Opcional. Especifica a versão da operação a ser usada para esta solicitação. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure.
`x-ms-client-request-id`	Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres KiB (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar o Armazenamento de Filas do Azure.

Corpo da solicitação

Nenhum.

Solicitação de exemplo

Consulte a seção "Solicitação e resposta de exemplo" mais adiante neste artigo.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta que contém a lista de filas.

Código de status

Uma operação bem-sucedida retorna o código de status 200 (OK). Para obter informações sobre códigos de status, consulte Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também pode incluir cabeçalhos HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de resposta	Descrição
`x-ms-request-id`	Esse cabeçalho identifica exclusivamente a solicitação que foi feita e pode ser usado para solucionar problemas da solicitação. Para obter mais informações, consulte Solução de problemas de operações de API.
`x-ms-version`	Indica a versão do Armazenamento de Filas usada para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e mais recente.
`Date`	Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
`x-ms-client-request-id`	Você pode usar esse cabeçalho para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do `x-ms-client-request-id` cabeçalho, se ele estiver presente na solicitação. O valor é no máximo 1024 caracteres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Corpo da resposta

O formato do corpo da resposta é o seguinte. Observe que os Prefixelementos , Markere MaxResults só estarão presentes se você os especificou no URI. O NextMarker elemento terá um valor somente se os resultados da lista não estiverem concluídos.

Para a versão 2013-08-15 e posterior, o AccountName atributo para o EnumerationResults elemento foi renomeado para ServiceEndpoint. Além disso, o elemento Url em Queue foi removido.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.queue.core.windows.net/">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Queues>  
    <Queue>  
      <Name>string-value</Name>  
      <Metadata>  
      <metadata-name>value</metadata-name>  
    <Metadata>  
    </Queue>  
  <NextMarker />  
</EnumerationResults>

O elemento Metadata estará presente apenas se o parâmetro include=metadata tiver sido especificado no URI. No elemento Metadata, o valor de cada par de nome-valor é listado em um elemento correspondente ao nome do par.

Se um par de nome-valor de metadados violar as restrições de nomenclatura impostas pela versão 2009-09-19, o corpo da resposta indicará o nome problemático dentro de um elemento x-ms-invalid-name, conforme mostrado no seguinte fragmento XML:

  
…  
<Metadata>  
  <MyMetadata1>first value</MyMetadata1>  
  <MyMetadata2>second value</MyMetadata2>  
  <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>  
<Metadata>  
…

Resposta de exemplo

Consulte a seção "Solicitação e resposta de exemplo" mais adiante neste artigo.

Autorização

Somente o proprietário da conta pode chamar essa operação.

Comentários

Se você especificar um valor para o maxresults parâmetro e o número de filas a serem retornadas exceder esse valor ou exceder o valor padrão para maxresults, o corpo da resposta conterá um NextMarker elemento . Esse elemento indica a próxima fila a ser retornada em uma solicitação subsequente. Para retornar o próximo conjunto de itens, especifique o valor NextMarker como o parâmetro de marcador no URI para a solicitação subsequente.

Observe que o valor de NextMarker deve ser tratado como opaco.

As filas são listadas em ordem alfabética no corpo da resposta.

Exemplo de solicitação e resposta

Aqui está um URI de exemplo que solicita a lista de filas de uma conta. Ele define o máximo de resultados a serem retornados para a operação inicial como três.

GET https://myaccount.queue.core.windows.net?comp=list&maxresults=3&include=metadata HTTP/1.1

A solicitação é enviada com estes cabeçalhos:

x-ms-version: 2013-08-15  
x-ms-date: Wed, 23 Oct 2013 00:55:16 GMT  
Authorization: SharedKey myaccount:Q7tar7qqM2LD/Wey7OQNPP3hMNap9wjg+g9AlAYeFls=

Os cabeçalhos de código de status e de resposta são retornados da seguinte forma:

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Wed, 23 Oct 2013 00:56:38 GMT  
x-ms-version: 2013-08-15  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0

A resposta XML para essa solicitação é a seguinte. Observe que o NextMarker elemento segue o conjunto de filas e inclui o nome da próxima fila a ser retornada.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.queue.core.windows.net/">  
  <Prefix>q</Prefix>  
  <MaxResults>3</MaxResults>  
  <Queues>  
    <Queue>  
      <Name>q1</Name>  
      <Metadata>  
        <Color>red</Color>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      <Metadata>  
    </Queue>  
    <Queue>  
      <Name>q2</Name>  
      <Metadata>  
        <Color>blue</Color>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      <Metadata>  
    </Queue>  
    <Queue>  
      <Name>q3</Name>  
      <Metadata>  
        <Color>yellow</Color>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      <Metadata>  
    </Queue>  
  </Queues>  
  <NextMarker>q4</NextMarker>  
</EnumerationResults>

A operação subsequente da lista especifica o marcador no URI de solicitação, da seguinte forma. O próximo conjunto de resultados é retornado, começando com a fila especificada pelo marcador. Aqui está o URI da solicitação subsequente:

https://myaccount.queue.core.windows.net?comp=list&maxresults=3&include=metadata&prefix=q&marker=q4

O corpo da resposta para essa operação é o seguinte:

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.queue.core.windows.net/">  
  <Prefix>q</Prefix>  
  <Marker>q4</Marker>  
  <MaxResults>3</MaxResults>  
  <Queues>  
    <Queue>  
      <Name>q4</Name>  
      <Metadata>  
        <Color>green</Color>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      <Metadata>  
    </Queue>  
    <Queue>  
      <Name>q5</Name>  
      <Metadata>  
        <Color>violet</Color>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      <Metadata>  
    </Queue>  
  </Queues>  
  <NextMarker />  
</EnumerationResults>

Confira também

Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Códigos de erro do Armazenamento de Filas