Início rápido: 2 - Carregar dados para um índice do Azure Search usando C#Quickstart: 2 - Load data to an Azure Search index using C#

Este artigo mostra como importar dados para um índice do Azure Search usando C# e o SDK do .NET.This article shows you how to import data into an Azure Search index using C# and the .NET SDK. Efetuar push de documentos para o índice é realizado executando estas tarefas:Pushing documents into your index is accomplished by performing these tasks:

  • Crie um objeto SearchIndexClient para conectar um índice de pesquisa.Create a SearchIndexClient object to connect to a search index.
  • Crie um objeto IndexBatch contendo os documentos a serem adicionados, modificados ou excluídos.Create an IndexBatch object containing the documents to be added, modified, or deleted.
  • Chame o método Documents.Index no SearchIndexClient para carregar documentos para um índice.Call the Documents.Index method on SearchIndexClient to upload documents to an index.

Pré-requisitosPrerequisites

Crie um índice do Azure Search e um objeto SearchServiceClient, conforme mostrado em "Criar um cliente".Create an Azure Search index and a SearchServiceClient object, as shown in "Create a client".

Criar um clienteCreate a client

Para importar dados, é necessário ter uma instância da classe SearchIndexClient.To import data, you need an instance of the SearchIndexClient class. Há várias abordagens para criar essa classe, incluindo o uso da instância SearchServiceClient que já foi criada.There are several approaches for creating this class, including using the SearchServiceClient instance that is already created.

Como o exemplo a seguir ilustra, é possível usar a instância SearchServiceCliente chamar o método Indexes.GetClient.As the following example illustrates, you can use the SearchServiceClient instance and call its Indexes.GetClient method. Esse snippet de código obtém um SearchIndexClient para o índice nomeado "hotéis" de um SearchServiceClient nomeado serviceClient.This snippet obtains a SearchIndexClient for the index named "hotels" from a SearchServiceClient named serviceClient.

ISearchIndexClient indexClient = serviceClient.Indexes.GetClient("hotels");

SearchIndexClient tem uma propriedade Documents.SearchIndexClient has a Documents property. Esta propriedade fornece todos os métodos que você precisa para adicionar, modificar, excluir ou consultar documentos no índice.This property provides all the methods you need to add, modify, delete, or query documents in your index.

Observação

Em um aplicativo de pesquisa típico, a consulta e a indexação são tratadas separadamente.In a typical search application, querying and indexing are handled separately. Embora Indexes.GetClient seja conveniente porque é possível reutilizar objetos como SearchCredentials, uma abordagem mais robusta envolve a criação de SearchIndexClient diretamente para que você possa passar uma chave de consulta, em vez de uma chave de administração.While Indexes.GetClient is convenient because you can reuse objects like SearchCredentials, a more robust approach involves creating the SearchIndexClient directly so that you can pass in a query key instead of an admin key. Essa prática é consistente com o princípio de privilégios mínimos e ajuda a tornar o aplicativo mais seguro.This practice is consistent with the principle of least privilege and helps to make your application more secure. Você construirá um SearchIndexClient no próximo exercício.You'll construct a SearchIndexClient in the next exercise. Para obter mais informações sobre chaves, consulte Criar e gerenciar chaves de API para um serviço Azure Search.For more information about keys, see Create and manage api-keys for an Azure Search service.

Construir IndexBatchConstruct IndexBatch

Para importar dados usando o SDK do .NET, empacote os dados em um objeto IndexBatch.To import data using the .NET SDK, package up your data into an IndexBatch object. Um IndexBatch encapsula uma coleção de objetos IndexAction, cada um contendo um documento e uma propriedade que informa ao Azure Search qual ação executar nesse documento (carregar, mesclar, excluir e mergeOrUpload).An IndexBatch encapsulates a collection of IndexAction objects, each of which contains a document and a property that tells Azure Search what action to perform on that document (upload, merge, delete, and mergeOrUpload). Para obter mais informações sobre ações de indexação, consulte Ações de indexação: carregar, mesclar, mergeOrUpload, excluir.For more information about indexing actions, see Indexing actions: upload, merge, mergeOrUpload, delete.

Assumindo que você sabe quais ações executar nos documentos, você está pronto para construir o IndexBatch.Assuming you know which actions to perform on your documents, you are ready to construct the IndexBatch. O exemplo a seguir mostra como criar um lote com algumas ações diferentes.The example below shows how to create a batch with a few different actions. O exemplo usa uma classe personalizada chamada Hotel que mapeia para um documento no índice "hotéis".The example uses a custom class called Hotel that maps to a document in the "hotels" index.

var actions =
    new IndexAction<Hotel>[]
    {
        IndexAction.Upload(
            new Hotel()
            {
                HotelId = "1",
                BaseRate = 199.0,
                Description = "Best hotel in town",
                DescriptionFr = "Meilleur hôtel en ville",
                HotelName = "Fancy Stay",
                Category = "Luxury",
                Tags = new[] { "pool", "view", "wifi", "concierge" },
                ParkingIncluded = false,
                SmokingAllowed = false,
                LastRenovationDate = new DateTimeOffset(2010, 6, 27, 0, 0, 0, TimeSpan.Zero),
                Rating = 5,
                Location = GeographyPoint.Create(47.678581, -122.131577)
            }),
        IndexAction.Upload(
            new Hotel()
            {
                HotelId = "2",
                BaseRate = 79.99,
                Description = "Cheapest hotel in town",
                DescriptionFr = "Hôtel le moins cher en ville",
                HotelName = "Roach Motel",
                Category = "Budget",
                Tags = new[] { "motel", "budget" },
                ParkingIncluded = true,
                SmokingAllowed = true,
                LastRenovationDate = new DateTimeOffset(1982, 4, 28, 0, 0, 0, TimeSpan.Zero),
                Rating = 1,
                Location = GeographyPoint.Create(49.678581, -122.131577)
            }),
        IndexAction.MergeOrUpload(
            new Hotel()
            {
                HotelId = "3",
                BaseRate = 129.99,
                Description = "Close to town hall and the river"
            }),
        IndexAction.Delete(new Hotel() { HotelId = "6" })
    };

var batch = IndexBatch.New(actions);

Nesse caso, estamos usando Upload, MergeOrUpload e Delete como nossas ações de pesquisa, conforme especificado pelos métodos chamados na classe IndexAction.In this case, we are using Upload, MergeOrUpload, and Delete as our search actions, as specified by the methods called on the IndexAction class.

Suponha que o índice de exemplo "hotels" já esteja preenchido com vários documentos.Assume that this example "hotels" index is already populated with a number of documents. Observe como não precisamos especificar todos os campos de documento possíveis ao usar MergeOrUpload e como especificamos apenas a chave do documento (HotelId) ao usar Delete.Note how we did not have to specify all the possible document fields when using MergeOrUpload and how we only specified the document key (HotelId) when using Delete.

Além disso, observe que você só pode incluir até 1000 documentos em uma única solicitação de indexação.Also, note that you can only include up to 1000 documents in a single indexing request.

Observação

Neste exemplo, estamos aplicando ações diferentes para documentos diferentes.In this example, we are applying different actions to different documents. Se você quisesse executar as mesmas ações em todos os documentos do lote, em vez de chamar IndexBatch.New, poderia usar os outros métodos estáticos de IndexBatch.If you wanted to perform the same actions across all documents in the batch, instead of calling IndexBatch.New, you could use the other static methods of IndexBatch. Por exemplo, você poderia criar lotes chamando IndexBatch.Merge, IndexBatch.MergeOrUpload ou IndexBatch.Delete.For example, you could create batches by calling IndexBatch.Merge, IndexBatch.MergeOrUpload, or IndexBatch.Delete. Esses métodos usam um conjunto de documentos (objetos do tipo Hotel neste exemplo) em vez de objetos IndexAction.These methods take a collection of documents (objects of type Hotel in this example) instead of IndexAction objects.

Chamar Documents.IndexCall Documents.Index

Agora que você tem um objeto IndexBatch inicializado, pode enviá-lo para o índice chamando Documents.Index em seu objeto SearchIndexClient.Now that you have an initialized IndexBatch object, you can send it to the index by calling Documents.Index on your SearchIndexClient object. O exemplo a seguir mostra como chamar Index, assim como algumas etapas adicionais que você precisa executar:The following example shows how to call Index, as well as some extra steps you will need to perform:

try
{
    indexClient.Documents.Index(batch);
}
catch (IndexBatchException e)
{
    // Sometimes when your Search service is under load, indexing will fail for some of the documents in
    // the batch. Depending on your application, you can take compensating actions like delaying and
    // retrying. For this simple demo, we just log the failed document keys and continue.
    Console.WriteLine(
        "Failed to index some of the documents: {0}",
        String.Join(", ", e.IndexingResults.Where(r => !r.Succeeded).Select(r => r.Key)));
}

Console.WriteLine("Waiting for documents to be indexed...\n");
Thread.Sleep(2000);

Observe try/catch em torno da chamada para o método Index.Note the try/catch surrounding the call to the Index method. O bloco catch lida com um caso de erro importante para a indexação.The catch block handles an important error case for indexing. Se o serviço de Azure Search não indexar alguns documentos no lote, uma IndexBatchException será lançada por Documents.Index.If your Azure Search service fails to index some of the documents in the batch, an IndexBatchException is thrown by Documents.Index. Isso pode acontecer se você estiver indexando documentos enquanto o serviço estiver sob carga pesada.This can happen if you are indexing documents while your service is under heavy load. É altamente recomendável a manipulação explícita desse caso em seu código.We strongly recommend explicitly handling this case in your code. Você pode atrasar e repetir a indexação de documentos que falharam, ou você pode registrar em log e continuar, como faz o exemplo, ou pode alguma outra coisa, dependendo dos requisitos de consistência de dados do aplicativo.You can delay and then retry indexing the documents that failed, or you can log and continue like the sample does, or you can do something else depending on your application's data consistency requirements.

Por fim, o código no exemplo acima, atrasa por dois segundos.Finally, the code in the example above delays for two seconds. A indexação ocorre de maneira assíncrona em seu serviço de Azure Search, portanto, o exemplo de aplicativo precisa aguardar alguns instantes para garantir que os documentos estejam disponíveis para pesquisa.Indexing happens asynchronously in your Azure Search service, so the sample application needs to wait a short time to ensure that the documents are available for searching. Normalmente, atrasos como esses só são necessários em demonstrações, testes e exemplos de aplicativos.Delays like this are typically only necessary in demos, tests, and sample applications.

Para obter mais informações sobre o processamento de documentos, consulte "Como o SDK do .NET trata documentos".For more information about document processing, see "How the .NET SDK handles documents".

Próximas etapasNext steps

Após preencher o índice do Azure Search, a próxima etapa será a emissão de consultas para pesquisar documentos.After populating your Azure Search index, the next step is issuing queries to search for documents.