Gerenciar Propriedades de contêiner e metadados com o .NETManage container properties and metadata with .NET

Os contêineres de blob dão suporte a propriedades do sistema e metadados definidos pelo usuário, além dos dados que eles contêm.Blob containers support system properties and user-defined metadata, in addition to the data they contain. Este artigo mostra como gerenciar Propriedades do sistema e metadados definidos pelo usuário com a biblioteca de cliente de armazenamento do Azure para .net.This article shows how to manage system properties and user-defined metadata with the Azure Storage client library for .NET.

Sobre propriedades e metadadosAbout properties and metadata

  • Propriedades do sistema: As propriedades do sistema existem em cada recurso de armazenamento de BLOBs.System properties: System properties exist on each Blob storage resource. Algumas podem ser lidas ou definidas, enquanto outras são de somente leitura.Some of them can be read or set, while others are read-only. Internamente, algumas propriedades do sistema correspondem a certos cabeçalhos HTTP padrão.Under the covers, some system properties correspond to certain standard HTTP headers. A biblioteca de cliente de armazenamento do Azure para .NET mantém essas propriedades para você.The Azure Storage client library for .NET maintains these properties for you.

  • Metadados definidos pelo usuário: Os metadados definidos pelo usuário consistem em um ou mais pares de nome-valor que você especifica para um recurso de armazenamento de BLOBs.User-defined metadata: User-defined metadata consists of one or more name-value pairs that you specify for a Blob storage resource. Você pode usar metadados para armazenar valores adicionais com o recurso.You can use metadata to store additional values with the resource. Os valores de metadados são apenas para suas próprias finalidades e não afetam o comportamento do recurso.Metadata values are for your own purposes only, and do not affect how the resource behaves.

A recuperação de valores de propriedade e metadados para um recurso de armazenamento de BLOBs é um processo de duas etapas.Retrieving property and metadata values for a Blob storage resource is a two-step process. Antes de poder ler esses valores, será necessário buscá-los explicitamente, chamando o método FetchAttributes ou FetchAttributesAsync.Before you can read these values, you must explicitly fetch them by calling the FetchAttributes or FetchAttributesAsync method. A exceção a essa regra é que os métodos Exists e ExistsAsync chamam o método fetchattributes apropriado nos bastidores.The exception to this rule is that the Exists and ExistsAsync methods call the appropriate FetchAttributes method under the covers. Ao chamar um desses métodos, você também não precisa chamar fetchattributes.When you call one of these methods, you do not need to also call FetchAttributes.

Importante

Se você achar que a propriedade ou os valores de metadados de um recurso de armazenamento não foram preenchidos, verifique se o código chama o método FetchAttributes ou FetchAttributesAsync.If you find that property or metadata values for a storage resource have not been populated, then check that your code calls the FetchAttributes or FetchAttributesAsync method.

Os pares de nome/valor de metadados são cabeçalhos HTTP válidos e, portanto, devem aderir a todas as restrições que regem os cabeçalhos HTTP.Metadata name/value pairs are valid HTTP headers, and so should adhere to all restrictions governing HTTP headers. Os nomes de metadados devem ser nomes de cabeçalho HTTP C# válidos e identificadores válidos, podem conter apenas caracteres ASCII e devem ser tratados como não diferenciando maiúsculas de minúsculas.Metadata names must be valid HTTP header names and valid C# identifiers, may contain only ASCII characters, and should be treated as case-insensitive. Os valores de metadados que contêm caracteres não ASCII devem ser codificados em base64 ou codificados por URL.Metadata values containing non-ASCII characters should be Base64-encoded or URL-encoded.

Recuperar propriedades do contêinerRetrieve container properties

Para recuperar as propriedades do contêiner, chame um dos seguintes métodos:To retrieve container properties, call one of the following methods:

O exemplo de código a seguir busca as propriedades do sistema de um contêiner e grava alguns valores de propriedade em uma janela de console:The following code example fetches a container's system properties and writes some property values to a console window:

private static async Task ReadContainerPropertiesAsync(CloudBlobContainer container)
{
    try
    {
        // Fetch some container properties and write out their values.
        await container.FetchAttributesAsync();
        Console.WriteLine("Properties for container {0}", container.StorageUri.PrimaryUri);
        Console.WriteLine("Public access level: {0}", container.Properties.PublicAccess);
        Console.WriteLine("Last modified time in UTC: {0}", container.Properties.LastModified);
    }
    catch (StorageException e)
    {
        Console.WriteLine("HTTP error code {0}: {1}",
                            e.RequestInformation.HttpStatusCode,
                            e.RequestInformation.ErrorCode);
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

Definir e recuperar metadadosSet and retrieve metadata

Você pode especificar os metadados como um ou mais pares de nome-valor em um recurso de contêiner ou blob.You can specify metadata as one or more name-value pairs on a blob or container resource. Para definir metadados, adicione pares de nome-valor à coleção de metadados no recurso e, em seguida, chame um dos seguintes métodos para gravar os valores:To set metadata, add name-value pairs to the Metadata collection on the resource, then call one of the following methods to write the values:

O nome dos metadados deve estar em conformidade com as convenções de nomenclatura para os identificadores de C#.The name of your metadata must conform to the naming conventions for C# identifiers. Os nomes de metadados preservam o caso em que foram criados, mas não diferenciam maiúsculas de minúsculas quando definidos ou lidos.Metadata names preserve the case with which they were created, but are case-insensitive when set or read. Se dois ou mais cabeçalhos de metadados com o mesmo nome forem enviados para um recurso, o armazenamento de blob retornará o código de erro HTTP 400 (solicitação inadequada).If two or more metadata headers with the same name are submitted for a resource, Blob storage returns HTTP error code 400 (Bad Request).

O exemplo de código a seguir define os metadados em um contêiner.The following code example sets metadata on a container. Um valor é definido usando o método Add da coleção.One value is set using the collection's Add method. O outro valor é definido usando a sintaxe implícita de chave/valor.The other value is set using implicit key/value syntax. Ambos são válidos.Both are valid.

public static async Task AddContainerMetadataAsync(CloudBlobContainer container)
{
    try
    {
        // Add some metadata to the container.
        container.Metadata.Add("docType", "textDocuments");
        container.Metadata["category"] = "guidance";

        // Set the container's metadata.
        await container.SetMetadataAsync();
    }
    catch (StorageException e)
    {
        Console.WriteLine("HTTP error code {0}: {1}",
                            e.RequestInformation.HttpStatusCode,
                            e.RequestInformation.ErrorCode);
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

Para recuperar metadados, chame o método FetchAttributes ou FetchAttributesAsync no blob ou contêiner para preencher a coleção de Metadados e leia os valores, conforme mostrado no exemplo abaixo.To retrieve metadata, call the FetchAttributes or FetchAttributesAsync method on your blob or container to populate the Metadata collection, then read the values, as shown in the example below.

public static async Task ReadContainerMetadataAsync(CloudBlobContainer container)
{
    try
    {
        // Fetch container attributes in order to populate the container's properties and metadata.
        await container.FetchAttributesAsync();

        // Enumerate the container's metadata.
        Console.WriteLine("Container metadata:");
        foreach (var metadataItem in container.Metadata)
        {
            Console.WriteLine("\tKey: {0}", metadataItem.Key);
            Console.WriteLine("\tValue: {0}", metadataItem.Value);
        }
    }
    catch (StorageException e)
    {
        Console.WriteLine("HTTP error code {0}: {1}",
                            e.RequestInformation.HttpStatusCode,
                            e.RequestInformation.ErrorCode);
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

Recursos para desenvolvimento com o .NETResources for development with .NET

Os links a seguir fornecem recursos úteis para os desenvolvedores que usam a biblioteca de cliente de armazenamento do Azure para .NET.The links below provide useful resources for developers using the Azure Storage client library for .NET.

APIs comuns do armazenamento do AzureAzure Storage common APIs

APIs de armazenamento de BlobBlob storage APIs

Ferramentas .NET.NET tools

Consulte tambémSee also