Partilhar via


Alças de Lista

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 Yes
NFS No

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.

Ver também