Compartilhar via


Listar identificadores

A List Handles operação 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 Sim
NFS Não

Solicitação

Você pode construir a solicitação da List Handles seguinte maneira. HTTPS é recomendado.

Método URI da solicitação Versão HTTP
GET https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles HTTP/1.1

Substitua os componentes do caminho mostrados no URI da solicitação pelos seus próprios, como segue:

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

Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados.

Parâmetros do 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 List Handles operação. 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 ao cliente.
maxresults Opcional. Especifica o número máximo de identificadores feitos em arquivos ou diretórios a serem retornados.

A configuração de maxresults com um valor menor ou igual a zero resulta em um 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 Configurando tempos limite para operações de Arquivos do Azure.
sharesnapshot Opcional. O sharesnapshot parâmetro é um valor opaco DateTime que, quando presente, especifica o compartilhamento instantâneo consultar a lista de identificadores.

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 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 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 Arquivos do Azure.
x-ms-recursive Opcional. Um valor booliano 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 o cabeçalho especificar um token OAuth. O valor aceitável é backup. Esse cabeçalho especifica que o Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action deve ser concedido se eles estiverem incluídos na política RBAC atribuída à identidade autorizada usando o Authorization cabeçalho . 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 de 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 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
Content-Type Especifica o formato em que os resultados são retornados. Atualmente, esse 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 do 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 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 da resposta XML é mostrado a seguir. Observe que os Markerelementos , ShareSnapshote MaxResults só estarão presentes se você os especificou no URI de solicitação. O NextMarker elemento terá um valor somente se os resultados da lista não estiverem concluídos.

<?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>
            <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 Finalidade
HandleId ID do identificador de serviço XSMB, UINT64. Usado para identificar o identificador.
Path Nome do arquivo, incluindo o caminho completo, começando pela raiz de compartilhamento. Cadeia de caracteres. Usado para identificar o nome do objeto para o qual o identificador está aberto.
ClientIp IP do cliente que abriu o identificador. Cadeia de caracteres. 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 de cliente/servidor, devido à rede ou a outras falhas. O campo será incluído no corpo da resposta somente se o evento de desconexão tiver ocorrido e o identificador for reaberto.
FileId ID do arquivo, UINT64. FileId identifica exclusivamente o arquivo. Ele é útil durante as renomeações, porque o FileId não é alterado.
ParentId ID do arquivo pai, UINT64. ParentId identifica exclusivamente o diretório. Isso é útil durante as renomeações, porque 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á por porcentagem (por RFC 2396) todos os Path valores de elemento que contêm caracteres inválidos em XML (especificamente, U+FFFE ou U+FFFF). Se codificado, o Path elemento incluirá um Encoded=true atributo . Observe que isso só ocorrerá para os valores de Path elemento que contêm os caracteres inválidos em XML, não os elementos restantes Path na resposta.

Autorização

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

Comentários

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.

Confira também