Listar identificadores

Artigo
02/22/2025

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

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado	Disponível
SMB
NFS

Pedir

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

Método	URI de solicitação	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 da solicitação por seus próprios, da seguinte maneira:

Componente path	Descrição
`myaccount`	O nome da sua conta de armazenamento.
`myshare`	O nome do 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 Nomenclatura e referência a 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 de `List Handles`. A operação retornará um valor de marcador dentro do corpo da resposta, se a lista retornada não estiver concluída. 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 usados em arquivos ou diretórios a serem retornados. Definir `maxresults` como um valor menor ou igual a zero resulta em 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 Definir tempos limite para operações de Arquivos do Azure.
`sharesnapshot`	Opcional. O parâmetro `sharesnapshot` é um valor opaco `DateTime` 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 cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho de 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 UTC (Tempo Universal Coordenado) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
`x-ms-version`	Necessário para todas as solicitações autorizadas, opcional para solicitações anônimas. 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 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 arquivos do Azure.
`x-ms-recursive`	Opcional. Um valor booliano que especifica se a operação também deve se aplicar aos arquivos e subdiretórios do diretório especificado no URI.
`x-ms-file-request-intent`	Necessário se `Authorization` cabeçalho especificar um token OAuth. O valor aceitável é `backup`. Esse 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 booliano especifica se um ponto à direita presente na URL da solicitação deve ser cortado ou não. Para obter mais informações, consulte Nomenclatura e referência a compartilhamentos, diretórios, arquivos e metadados.

Corpo da solicitação

Nenhum.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta no 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 Status e códigos de erro.

Cabeçalhos de resposta

A resposta dessa 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 de protocolo HTTP/1.1 .

Cabeçalhos comuns

Cabeçalho de resposta	Descrição
`Content-Type`	Especifica o formato no qual os resultados são retornados. Atualmente, esse valor está `application/xml`.
`x-ms-request-id`	Esse cabeçalho identifica exclusivamente a solicitação 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 da resposta

O formato da resposta XML é o seguinte. Observe que os elementos Marker, ShareSnapshote MaxResults só estarão presentes se você especificá-los no URI da solicitação. O elemento NextMarker tem um valor somente se os resultados da lista não estiverem concluídos.

ClientName campo em resposta é opcional e retornado somente 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:

Campo	Descrição	Propósito
`HandleId`	ID do identificador de serviço XSMB, UINT64.	Usado para identificar o identificador.
`Path`	Nome do arquivo, incluindo o caminho completo, começando na raiz do compartilhamento. Corda.	Usado para identificar o nome do objeto para o qual o identificador está aberto.
`ClientIp`	IP do cliente que abriu o identificador. Corda.	Usado para decidir se o identificador pode ter sido vazado.
`ClientName`	Campo opcional. Com suporte em 2024-02-04 e superior. Nome do cliente (Nome de Usuário da Estação de Trabalho ou do SISTEMA Operacional) que abriu o identificador. Corda.	Usado para decidir se o identificador pode ter sido vazado.
`OpenTime`	O identificador de tempo foi aberto (UTC). `DateTime` como Cadeia de Caracteres.	Usado para decidir se o identificador pode ter sido vazado. Identificadores vazados normalmente estão abertos há muito tempo.
`LastReconnectTime`	O identificador de tempo foi aberto (UTC). `DateTime` como Cadeia de Caracteres.	Usado para decidir se o identificador foi reaberto após uma desconexão cliente/servidor, devido à rede ou a outras falhas. O campo é incluído no corpo da resposta somente se o evento de desconexão ocorreu e o identificador foi reaberto.
`FileId`	ID do arquivo, UINT64.	`FileId` identifica exclusivamente o arquivo. É útil durante as renomeações, pois o `FileId` não é alterado.
`ParentId`	ID do arquivo pai, UINT64.	`ParentId` identifica exclusivamente o diretório. Isso é útil durante as renomeações, pois o `ParentId` não é alterado.
`SessionId`	ID da 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 associar 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 no serviço versã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 os identificadores restantes. A ausência de `NextMarker` indica que todos os identificadores relevantes foram listados.

Nas versões 2021-12-02 e mais recentes, List Handles codificará percentual (por RFC 2396) todos os valores de elemento Path que contêm 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 os elementos de Path restantes na resposta.

ClientName tem suporte na versão 2024-02-04 e posterior.

Autorização

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

Observações

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

Consulte também

operações de em arquivos
operações de em diretórios

Compartilhar via