Actualización a la versión 11 del SDK de .NET de Azure AI Search

  • Artículo

Si la solución de búsqueda se basa en el SDK de Azure para .NET, este artículo le ayuda a migrar el código de versiones anteriores de Microsoft.Azure.Search a la versión 11, la nueva biblioteca cliente Azure.Search.Documents. La versión 11 es una biblioteca cliente totalmente rediseñada que ha publicado el equipo de desarrollo de Azure SDK (las versiones anteriores fueron creadas por el equipo de desarrollo de Azure AI Search).

Todas las características de la versión 10 se implementan en la versión 11. Entre las principales diferencias se incluyen:

  • Un paquete (Azure.Search.Documents) en lugar de cuatro
  • Tres clientes en lugar de dos: SearchClient, SearchIndexClient y SearchIndexerClient
  • Diferencias de nomenclatura en una serie de API y pequeñas diferencias estructurales que simplifican algunas tareas

El registro de cambios de la biblioteca cliente tiene una lista detallada de actualizaciones. Puede revisar una versión resumida en este artículo.

Todos los fragmentos y ejemplos de código de C# en la documentación de producto de Azure AI Search se han revisado para indicar la nueva biblioteca cliente Azure.Search.Documents.

¿Por qué actualizar?

A continuación se resumen las ventajas de la actualización:

  • Se agregan nuevas características solo a Azure.Search.Documents. La versión anterior, Microsoft.Azure.Search, se ha retirado. Las actualizaciones de las bibliotecas en desuso se limitan únicamente a correcciones de errores de alta prioridad.

  • Coherencia con otras bibliotecas cliente de Azure. Azure.Search.Documents tiene una dependencia de Azure.Core y System.Text.Json, y sigue enfoques convencionales para tareas comunes como conexiones de cliente y autorización.

Microsoft.Azure.Search se ha retirado oficialmente. Si usa una versión anterior, se recomienda actualizar a la siguiente versión superior, repitiendo el proceso sucesivamente hasta llegar a la versión 11 y Azure.Search.Documents. Una estrategia de actualización incremental facilita la búsqueda y corrección de incidencias de bloqueo. Consulte la documentación de la versión anterior para obtener instrucciones.

Comparación de paquetes

La versión 11 consolida y simplifica la administración de paquetes para que haya menos que administrar.

Versión 10 y anteriores Versión 11
Microsoft.Azure.Search
Microsoft.Azure.Search.Service
Microsoft.Azure.Search.Data
Microsoft.Azure.Search.Common		 Paquete Azure.Search.Documents

Comparación de clientes

En la siguiente tabla se relacionan las bibliotecas cliente de las dos versiones.

Operaciones de cliente Microsoft.Azure.Search (v10) Azure.Search.Documents (v11)
Tiene como destino la colección de documentos de un índice (consultas e importación de datos) SearchIndexClient SearchClient
Tiene como destino objetos relacionados con índices (índices, analizadores, mapas de sinónimos) SearchServiceClient SearchIndexClient
Tiene como destino objetos relacionados con el indexador (indexadores, orígenes de datos, conjuntos de aptitudes) SearchServiceClient SearchIndexerClient (nueva)

Precaución

Observe que SearchIndexClient existe en ambas versiones, pero tiene como destino diferentes operaciones. En la versión 10, SearchIndexClient crea índices y otros objetos. En la versión 11, SearchIndexClient funciona con índices existentes y tiene como destino la colección de documentos con las API de ingesta de datos y consultas. Para evitar confusiones al actualizar el código, tenga en cuenta el orden en que se actualizan las referencias de cliente. Si sigue la secuencia de pasos de actualización, debería poder mitigar cualquier problema de reemplazo de cadenas.

Nomenclatura y otras diferencias de API

Además de las diferencias de cliente (indicadas anteriormente y que, por tanto, se omitieron aquí), se ha cambiado el nombre de varias API y, en algunos casos, se han rediseñado. Las diferencias de nombre de clase se resumen en las siguientes secciones. Esta lista no es exhaustiva, pero agrupa los cambios de API por tarea, lo que puede resultar útil para las revisiones en bloques de código específicos. Para ver una lista de actualizaciones de API, consulte el registro de cambios de Azure.Search.Documents en GitHub.

Autenticación y cifrado

Versión 10 Equivalente en la versión 11
SearchCredentials AzureKeyCredential
EncryptionKey (sin documentar en la referencia de la API. La compatibilidad con esta API ha pasado a estar disponible con carácter general en la versión 10, pero solo estaba disponible en el SDK de versión preliminar). SearchResourceEncryptionKey

Índices, analizadores y mapas de sinónimos

Versión 10 Equivalente en la versión 11
Índice SearchIndex
Campo SearchField
DataType SearchFieldDataType
ItemError SearchIndexerError
Analyzer LexicalAnalyzer (también, de AnalyzerName a LexicalAnalyzerName)
AnalyzeRequest AnalyzeTextOptions
StandardAnalyzer LuceneStandardAnalyzer
StandardTokenizer LuceneStandardTokenizer (también, de StandardTokenizerV2 a LuceneStandardTokenizerV2)
TokenInfo AnalyzedTokenInfo
Tokenizador LexicalTokenizer (también, de TokenizerName a LexicalTokenizerName)
SynonymMap.Format Ninguno. Se eliminan las referencias a Format.

Las definiciones de campo se simplifican: SearchableField, SimpleField, ComplexField son nuevas API para crear definiciones de campo.

Indizadores, orígenes de datos y conjuntos de aptitudes

Versión 10 Equivalente en la versión 11
Indizador SearchIndexer
DataSource SearchIndexerDataSourceConnection
Aptitud SearchIndexerSkill
Conjunto de aptitudes SearchIndexerSkillset
DataSourceType SearchIndexerDataSourceType

Importación de datos

Versión 10 Equivalente en la versión 11
IndexAction IndexDocumentsAction
IndexBatch IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry() SearchIndexingBufferedSender

Solicitudes y respuestas de consultas

Versión 10 Equivalente en la versión 11
DocumentsOperationsExtensions.SearchAsync SearchClient.SearchAsync
DocumentSearchResult SearchResult o SearchResults, en función de si el resultado está en un único documento o en varios.
DocumentSuggestResult SuggestResults
SearchParameters SearchOptions
SuggestParameters SuggestOptions
SearchParameters.Filter SearchFilter (una nueva clase para construir expresiones de filtro de OData)

Serialización de JSON

De forma predeterminada, el SDK de Azure usa System.Text.Json para la serialización de JSON. Para ello, se basa en las capacidades de esas API para controlar las transformaciones de texto que se implementaron previamente a través de una clase nativa SerializePropertyNamesAsCamelCaseAttribute, que no tiene homólogo en la nueva biblioteca.

Para serializar los nombres de propiedad en camelCase, puede usar JsonPropertyNameAttribute (similar a este ejemplo).

Como alternativa, puede establecer una propiedad JsonNamingPolicy proporcionada en JsonSerializerOptions. El siguiente ejemplo de código System.Text.Json, tomado del archivo Léame Microsoft.Azure.Core.Spatial muestra el uso de camelCase sin tener que atribuir cada propiedad:

// Get the Azure AI Search service endpoint and read-only API key.
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));

// Create serializer options with our converter to deserialize geographic points.
JsonSerializerOptions serializerOptions = new JsonSerializerOptions
{
    Converters =
    {
        new MicrosoftSpatialGeoJsonConverter()
    },
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

SearchClientOptions clientOptions = new SearchClientOptions
{
    Serializer = new JsonObjectSerializer(serializerOptions)
};

SearchClient client = new SearchClient(endpoint, "mountains", credential, clientOptions);
Response<SearchResults<Mountain>> results = client.Search<Mountain>("Rainier");

Si usa Newtonsoft.Json para la serialización de JSON, puede pasar directivas de nomenclatura globales mediante atributos similares o mediante las propiedades de JsonSerializerSettings. Para obtener un ejemplo equivalente al anterior, consulte el ejemplo de deserialización de documentos en el archivo readme de Newtonsoft.Json.

Dentro de v11

Cada versión de una biblioteca cliente de Azure AI Search tiene como destino su versión correspondiente de la API de REST. La API REST se considera fundamental para el servicio, con SDK individuales que encapsulan una versión de la API REST. Como desarrollador de .NET, puede ser útil revisar la documentación de la API REST más detallada, para profundizar más en objetos u operaciones específicos. La versión 11 tiene como destino la especificación del servicio de búsqueda 2020-06-30.

La versión 11.0 es totalmente compatible con los siguientes objetos y operaciones:

  • Creación y administración de índices
  • Creación y administración de mapas de sinónimos
  • Creación y administración de indexadores
  • Creación y administración de orígenes de datos de indexadores
  • Creación y administración de conjuntos de aptitudes
  • Todos los tipos de consulta y sintaxis

Adiciones de la versión 11.1 (detalles en el registro de cambios):

Adiciones de la versión 11.2 (detalles en el registro de cambios):

Adiciones de la versión 11.3 (detalles en el registro de cambios):

Antes de actualizar

  • Se han actualizado los inicios rápidos, tutoriales y ejemplos de C# para usar el paquete Azure.Search.Documents. Se recomienda revisar los ejemplos y tutoriales para obtener información sobre las nuevas API antes de comenzar con una migración.

  • En Uso de Azure.Search.Documents en una aplicación de .NET con C# se indican las API más usadas. Incluso los usuarios con conocimientos de Azure AI Search pueden querer revisar esta introducción a la nueva biblioteca antes de llevar a cabo una migración.

Pasos para actualizar

Los siguientes pasos lo ayudarán a comenzar a realizar una migración de código recorriendo el primer conjunto de tareas necesarias, especialmente en lo que respecta a las referencias de cliente.

  1. Instale el paquete Azure.Search.Documents haciendo clic con el botón derecho en las referencias del proyecto y seleccione "Administrar paquetes NuGet..." en Visual Studio.

  2. Reemplace las directivas using para Microsoft.Azure.Search por las siguientes instrucciones using:

    using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

  3. Si hay clases que requieren la serialización de JSON, reemplace using Newtonsoft.Json por using System.Text.Json.Serialization.

  4. Revise el código de autenticación del cliente. En versiones anteriores, se usarían propiedades en el objeto de cliente para establecer la clave de API (por ejemplo, la propiedad SearchServiceClient. Credentials). En la versión actual, use la clase AzureKeyCredential para pasar la clave como una credencial, de modo que, si es necesario, pueda actualizar la clave de API sin crear objetos de cliente.

    Las propiedades del cliente se han simplificado a solo Endpoint, ServiceName y IndexName (cuando es necesario). En el ejemplo siguiente se usa la clase Uri del sistema para proporcionar el punto de conexión y la clase Environment para leer el valor de la clave:

    Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);

  5. Agregue nuevas referencias de cliente para los objetos relacionados con indexadores. Si usa indexadores, orígenes de usuario o conjuntos de habilidades, cambie las referencias de cliente a SearchIndexerClient. Este cliente es nuevo en la versión 11 y no tiene antecedente.

  6. Revise las colecciones y las listas. En el nuevo SDK, todas las listas son de solo lectura para evitar problemas descendentes si la lista contiene valores NULL. El cambio de código consiste en agregar elementos a una lista. Por ejemplo, en lugar de asignar cadenas a una propiedad Select, debe agregarlas como se indica a continuación:

    var options = new SearchOptions
 {
    SearchMode = SearchMode.All,
    IncludeTotalCount = true
 };

 // Select fields to return in results.
 options.Select.Add("HotelName");
 options.Select.Add("Description");
 options.Select.Add("Tags");
 options.Select.Add("Rooms");
 options.Select.Add("Rating");
 options.Select.Add("LastRenovationDate");

    Select, Facets, SearchFields, SourceFields, ScoringParameters y OrderBy son listas que ahora se deben reconstruir.

  7. Actualice las referencias de cliente para las consultas y la importación de datos. Las instancias de SearchIndexClient deben cambiarse a SearchClient. Para evitar confusión con los nombres, asegúrese de detectar todas las instancias antes de continuar con el siguiente paso.

  8. Actualice las referencias de cliente en los objetos index, synonym map y analyzer. Las instancias de SearchServiceClient deben cambiarse a SearchIndexClient.

  9. Para el resto del código, actualice las clases, los métodos y las propiedades para usar las API de la nueva biblioteca. La sección Nomenclatura y otras diferencias de API es un buen sitio para empezar, pero también puede revisar el registro de cambios.

    Si tiene problemas para encontrar API equivalentes, se recomienda registrar un problema en https://github.com/MicrosoftDocs/azure-docs/issues para que podamos mejorar la documentación o investigar el problema.

  10. Compile la solución. Después de corregir las advertencias o los errores de compilación, puede realizar cambios en la aplicación para aprovechar las ventajas de la nueva funcionalidad.

Últimos cambios

Dado los cambios radicales producidos en las bibliotecas y las API, una actualización a la versión 11 no es algo trivial y constituye un cambio importante en el sentido de que el código ya no será compatible con la versión 10 y anteriores. Para ver todas las diferencias, vea el registro de cambios de Azure.Search.Documents.

En lo que respecta a las actualizaciones de la versión del servicio, donde los cambios de código de la versión 11 se relacionan con la funcionalidad existente (y no solo con la refactorización de las API), encontrará los siguientes cambios de comportamiento:

  • El algoritmo de clasificación BM25 reemplaza el algoritmo de clasificación anterior por una tecnología más reciente. Los servicios nuevos usan este algoritmo de manera automática. En el caso de los servicios existentes, debe establecer los parámetros para usar el algoritmo nuevo.

  • Los resultados ordenados de los valores NULL han cambiado en esta versión y aparecen en primer lugar si la ordenación es asc y en el último si la ordenación es desc. Si ha escrito código para controlar cómo se ordenan los valores NULL, debe revisar y, posiblemente, quitar ese código si ya no es necesario.

Debido a estos cambios de comportamiento, es probable que haya ligeras variaciones cuando visualice los resultados clasificados.

Pasos siguientes