Alças de Lista

Artigo
06/01/2023

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

Disponibilidade do protocolo

Protocolo de partilha de ficheiros ativado	Disponível
SMB
NFS

Pedir

Pode construir o pedido da List Handles seguinte forma. É recomendado HTTPS.

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

Substitua os componentes de caminho apresentados no URI do pedido pelo seu, da seguinte forma:

Componente caminho	Description
`myaccount`	O nome da sua conta de armazenamento.
`myshare`	O nome da partilha de ficheiros.
`mydirectorypath`	Opcional. O caminho para o diretório.
`myfileordirectory`	O nome do ficheiro ou diretório.

Para obter detalhes sobre as restrições de nomenclatura de caminhos, veja Naming and referencing shares, directories, files, and metadata (Atribuir nomes e referenciar partilhas, diretórios, ficheiros e metadados).

Parâmetros do URI

Pode especificar os seguintes parâmetros adicionais no URI.

Parâmetro	Description
`marker`	Opcional. Um valor de cadeia que identifica a parte da lista a ser devolvida com a operação seguinte `List Handles` . A operação devolve um valor de marcador no corpo da resposta, se a lista devolvida não tiver sido concluída. Em seguida, pode utilizar o valor do marcador numa chamada subsequente para pedir 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 utilizados em ficheiros ou diretórios a devolver. Definir `maxresults` para um valor menor ou igual a zero resulta no código de resposta de erro 400 (Pedido Incorreto).
`timeout`	Opcional. O `timeout` parâmetro é expresso em segundos. Para obter mais informações, veja Setting timeouts for Ficheiros do Azure operations (Definir tempos limite para operações de Ficheiros do Azure).
`sharesnapshot`	Opcional. O `sharesnapshot` parâmetro é um valor opaco `DateTime` que, quando presente, especifica o instantâneo de partilha a consultar para a lista de identificadores.

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Cabeçalho do pedido	Description
`Authorization`	Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
`x-ms-version`	Necessário para todos os pedidos autorizados, opcional para pedidos anónimos. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.
`x-ms-client-request-id`	Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar Ficheiros do Azure.
`x-ms-recursive`	Opcional. Um valor booleano que especifica se a operação também deve ser aplicada aos ficheiros e subdiretórios do diretório especificado no URI.
`x-ms-file-request-intent`	Necessário se o `Authorization` cabeçalho especificar um token OAuth. O valor aceitável é `backup`. Este cabeçalho especifica que o `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` ou `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` deve ser concedido se estiver incluído na política RBAC atribuída à identidade autorizada com 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 Booleano especifica se um ponto à direita presente no URL do pedido deve ser cortado ou não. Para obter mais informações, veja Naming and referencing shares, directories, files, and metadata (Atribuir nomes e referenciar partilhas, diretórios, ficheiros e metadados).

Corpo do pedido

Nenhum.

Resposta

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

Código de estado

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

Cabeçalhos de resposta

A resposta para esta operação inclui os seguintes cabeçalhos. 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 no qual os resultados são devolvidos. Atualmente, este valor é `application/xml`.
`x-ms-request-id`	Este cabeçalho identifica exclusivamente o pedido que foi feito e pode ser utilizado para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API.
`x-ms-version`	Indica a versão do Ficheiros do Azure utilizado para executar o pedido.
`Date`	Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera este valor.
`x-ms-client-request-id`	Pode utilizar este cabeçalho para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do `x-ms-client-request-id` cabeçalho, se estiver presente no pedido. O valor é, no máximo, 1024 carateres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente no pedido, este cabeçalho não estará presente na resposta.

Corpo da resposta

O formato da resposta XML é o seguinte. Tenha em atenção que os Markerelementos , ShareSnapshote MaxResults só estão presentes se os tiver especificado no URI do pedido. O NextMarker elemento só tem um valor 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 seguinte descreve os campos do corpo da resposta:

Campo	Descrição	Objetivo
`HandleId`	ID do identificador do serviço XSMB, UINT64.	Utilizado para identificar o identificador.
`Path`	Nome do ficheiro, incluindo o caminho completo, a partir da raiz da partilha. Cadeia.	Utilizado para identificar o nome do objeto para o qual a alça está aberta.
`ClientIp`	IP do cliente que abriu o identificador. Cadeia.	Utilizado para decidir se o identificador pode ter sido vazado.
`OpenTime`	A alça de tempo foi aberta (UTC). `DateTime` como Cadeia.	Utilizado para decidir se o identificador pode ter sido vazado. Os identificadores vazados estão normalmente abertos há muito tempo.
`LastReconnectTime`	A alça de tempo foi aberta (UTC). `DateTime` como Cadeia.	Utilizado para decidir se o identificador foi reaberto após um cliente/servidor desligar, devido a redes ou outras falhas. O campo só é incluído no corpo da resposta se o evento de desconexão tiver ocorrido e a alça tiver sido reaberta.
`FileId`	ID do Ficheiro, UINT64.	`FileId` identifica exclusivamente o ficheiro. É útil durante os respetivos nomes, uma vez que o `FileId` não é alterado.
`ParentId`	ID do Ficheiro Principal, UINT64.	`ParentId` identifica exclusivamente o diretório. Isto é útil durante os nomes dos nomes, porque o `ParentId` não muda.
`SessionId`	ID da sessão SMB que especifica o contexto em que o identificador de ficheiro foi aberto. UINT64.	`SessionId` é incluído nos registos do visualizador de eventos quando as sessões são forçadas a desligar. Permite-lhe 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 ficheiro ou diretório.	Disponível na versão de serviço 2023-01-03 e posterior. Utilizado para consultar permissões de acesso mantidas num ficheiro ou diretório por vários identificadores abertos. Os valores possíveis são READ, WRITE e DELETE ou uma combinação destes valores.
`NextMarker`	Uma cadeia que descreve o identificador seguinte a ser listado. É devolvido quando é necessário listar mais identificadores para concluir o pedido.	A cadeia é utilizada em pedidos subsequentes para listar os restantes identificadores. 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 percentagem (por RFC 2396) todos os Path valores de elementos que contêm carateres inválidos em XML (especificamente, U+FFFE ou U+FFFF). Se codificado, o Path elemento incluirá um Encoded=true atributo. Tenha em atenção que isto só ocorrerá para os valores dos Path elementos que contêm os carateres inválidos em XML e não para os restantes Path elementos na resposta.

Autorização

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

Observações

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