Listar identificadores

Artigo
03/29/2023

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
NFS

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.