Identificadores de lista

Artigo
02/21/2025

A operação List Handles retorna uma lista de identificadores abertos em um diretório ou um arquivo. Opcionalmente, ele pode enumerar recursivamente identificadores abertos em diretórios e arquivos. Esta API está disponível a partir da versão 2018-11-09.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado	Disponível
PME
NFS

Solicitar

A solicitação List Handles é construída da seguinte forma. Recomendamos que você use HTTPS.

Método	Solicitar URI	Versão HTTP
OBTER	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles`	HTTP/1.1

Substitua os componentes de caminho mostrados no URI de solicitação pelo seu, da seguinte maneira:

Componente Caminho	Descrição
`myaccount`	O nome da sua conta de armazenamento.
`myshare`	O nome do seu compartilhamento de arquivos.
`mydirectorypath`	Opcional. O caminho para o diretório.
`myfileordirectory`	O nome do arquivo ou diretório.

Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomeando e referenciando compartilhamentos, diretórios, arquivos e metadados.

Parâmetros de URI

Você pode especificar os seguintes parâmetros adicionais no URI.

Parâmetro	Descrição
`marker`	Opcional. Um valor de cadeia de caracteres que identifica a parte da lista a ser retornada com a próxima operação `List Handles`. A operação retorna um valor de marcador dentro do corpo da resposta, se a lista retornada não estiver completa. Em seguida, você pode usar o valor do marcador em uma chamada subsequente para solicitar o próximo conjunto de itens de lista. O valor do marcador é opaco para o cliente.
`maxresults`	Opcional. Especifica o número máximo de identificadores tomados em arquivos ou diretórios a serem retornados. Definir `maxresults` para um valor menor ou igual a zero resulta no código de resposta de erro 400 (Solicitação incorreta).
`timeout`	Opcional. O parâmetro `timeout` é expresso em segundos. Para obter mais informações, consulte Definindo tempos limite para operações do Azure Files.
`sharesnapshot`	Opcional. O parâmetro `sharesnapshot` é um valor `DateTime` opaco que, quando presente, especifica o instantâneo de compartilhamento a ser consultado para a lista de identificadores.

Cabeçalhos de 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`	Necessário. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Necessário. Especifica o Tempo Universal Coordenado (UTC) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
`x-ms-version`	Obrigatório para todos os pedidos autorizados, opcional para pedidos anónimos. Especifica a versão da operação a ser usada para essa 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 de 1 kibibyte (KiB) que é registrado nos logs quando o log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações que o servidor recebe. Para obter mais informações, consulte Monitorar arquivos do Azure.
`x-ms-recursive`	Opcional. Um valor booleano que especifica se a operação também deve ser aplicada aos arquivos e subdiretórios do diretório especificado no URI.
`x-ms-file-request-intent`	Obrigatório se `Authorization` cabeçalho especificar um token OAuth. O valor aceitável é `backup`. Este cabeçalho especifica que os `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` ou `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` devem ser concedidos se forem incluídos na política RBAC atribuída à identidade autorizada usando o cabeçalho `Authorization`. Disponível para a versão 2022-11-02 e posterior.
`x-ms-allow-trailing-dot: { <Boolean> }`	Opcional. Versão 2022-11-02 e posterior. O valor booleano especifica se um ponto à direita presente na url da solicitação deve ser cortado ou não. Para obter mais informações, consulte Nomeando e referenciando compartilhamentos, diretórios, arquivos e metadados.

Corpo do pedido

Nenhuma.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta em formato XML.

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 na tabela 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çalhos comuns

Cabeçalho da resposta	Descrição
`Content-Type`	Especifica o formato no qual os resultados são retornados. Atualmente este valor é `application/xml`.
`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 dos Arquivos do Azure usada para executar a solicitação.
`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 cabeçalho `x-ms-client-request-id`, se ele estiver presente na solicitação. O valor é, no máximo, 1024 caracteres ASCII visíveis. Se o cabeçalho `x-ms-client-request-id` não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Corpo de resposta

O formato da resposta XML é o seguinte. Observe que os elementos Marker, ShareSnapshote MaxResults estarão presentes somente se você os tiver especificado no URI da solicitação. O elemento NextMarker tem um valor somente se os resultados da lista não estiverem completos.

ClientName campo em resposta é opcional e devolvido apenas quando disponível para o serviço.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults>
    <HandleList>
        <Handle>
            <HandleId>handle-id</HandleId>
            <Path>file-or-directory-name-including-full-path</Path>
            <FileId>file-id</FileId>
            <ParentId>parent-file-id</ParentId>
            <SessionId>session-id</SessionId>
            <ClientIp>client-ip</ClientIp>
            <ClientName>client-name</ClientName>
            <OpenTime>opened-time</OpenTime>
            <LastReconnectTime>lastreconnect-time</LastReconnectTime>
            <AccessRightList>
                <AccessRight>Read</AccessRight>
                <AccessRight>Write</AccessRight>
                <AccessRight>Delete</AccessRight>
            </AccessRightList>
        </Handle>
        ...
    </HandleList>
    <NextMarker>next-marker</NextMarker>
</EnumerationResults>

A tabela a seguir descreve os campos do corpo da resposta:

Domínio	Descrição	Finalidade
`HandleId`	ID do identificador de serviço XSMB, UINT64.	Usado para identificar a alça.
`Path`	Nome do arquivo, incluindo o caminho completo, a partir da raiz do compartilhamento. String.	Usado para identificar o nome do objeto para o qual o identificador está aberto.
`ClientIp`	IP do cliente que abriu a alça. String.	Usado para decidir se a alça pode ter sido vazada.
`ClientName`	Campo opcional. Suportado em 2024-02-04 e superior. Nome do cliente (nome de usuário da estação de trabalho ou do sistema operacional) que abriu a alça. String.	Usado para decidir se a alça pode ter sido vazada.
`OpenTime`	O identificador de tempo foi aberto (UTC). `DateTime` como String.	Usado para decidir se o identificador pode ter sido vazado. As alças vazadas normalmente estão abertas há muito tempo.
`LastReconnectTime`	O identificador de tempo foi aberto (UTC). `DateTime` como String.	Usado para decidir se o identificador foi reaberto após uma desconexão cliente/servidor, devido a falhas de rede ou outras. O campo é incluído no corpo da resposta somente se o evento de desconexão ocorreu e o identificador foi reaberto.
`FileId`	ID Ficheiro, UINT64.	`FileId` identifica exclusivamente o arquivo. É útil durante as renomeações, porque o `FileId` não muda.
`ParentId`	ID do arquivo pai, UINT64.	`ParentId` identifica exclusivamente o diretório. Isso é útil durante as renomeações, porque o `ParentId` não muda.
`SessionId`	ID de sessão SMB que especifica o contexto no qual o identificador de arquivo foi aberto. UINT64.	`SessionId` é incluído nos logs do visualizador de eventos quando as sessões são desconectadas à força. Ele permite que você associe um lote específico de identificadores vazados a um incidente de rede específico.
`AccessRightList`	As permissões de acesso concedidas ao identificador aberto no arquivo ou diretório.	Disponível na versão de serviço 2023-01-03 e posterior. Usado para consultar permissões de acesso mantidas em um arquivo ou diretório por vários identificadores abertos. Os valores possíveis são READ, WRITE e DELETE, ou uma combinação desses valores.
`NextMarker`	Uma cadeia de caracteres que descreve o próximo identificador a ser listado. Ele é retornado quando mais identificadores precisam ser listados para concluir a solicitação.	A cadeia de caracteres é usada em solicitações subsequentes para listar identificadores restantes. A ausência de `NextMarker` indica que todas as alças relevantes foram listadas.

Nas versões 2021-12-02 e mais recentes, List Handles codificará percentualmente (por RFC 2396) todos os valores de elementos Path que contenham caracteres inválidos em XML (especificamente, U+FFFE ou U+FFFF). Se codificado, o elemento Path incluirá um atributo Encoded=true. Observe que isso só ocorrerá para os valores do elemento Path que contêm os caracteres inválidos em XML, não para os elementos Path restantes na resposta.

ClientName é suportado na versão 2024-02-04 e posterior.

Autorização

Apenas o proprietário da conta pode chamar esta operação.

Comentários

O HandleId é um ID de identificador do lado do serviço, distinto do ID do identificador do cliente. O mapeamento entre os dois é possível no cliente.

Partilhar via