Tutorial: Extracción de texto y estructura de blobs JSON en Azure mediante API REST (Azure Cognitive Search)Tutorial: Extract text and structure from JSON blobs in Azure using REST APIs (Azure Cognitive Search)

Si tiene contenido de imagen o texto no estructurado en Azure Blob Storage, una canalización de enriquecimiento de inteligencia artificial puede ayudarle a extraer información y crear contenido útil para escenarios de búsqueda de texto completo o minería de conocimiento.If you have unstructured text or image content in Azure Blob storage, an AI enrichment pipeline can help you extract information and create new content that is useful for full-text search or knowledge mining scenarios. Aunque una canalización puede procesar archivos de imagen (JPG, PNG y TIFF), este tutorial se centra en el contenido basado en palabras y se aplica la detección de idioma y el análisis de texto para crear campos e información que puede aprovechar en consultas, facetas y filtros.Although a pipeline can process image files (JPG, PNG, TIFF), this tutorial focuses on word-based content, applying language detection and text analytics to create new fields and information that you can leverage in queries, facets, and filters.

  • Comience con documentos completos (texto no estructurado) como PDF, MD, DOCX y PPTX en Azure Blob Storage.Start with whole documents (unstructured text) such as PDF, MD, DOCX, and PPTX in Azure Blob storage.
  • Defina una canalización que extraiga texto, detecte el idioma, reconozca entidades y detecte frases clave.Define a pipeline that extracts text, detects language, recognizes entities, and detects key phrases.
  • Defina un índice para almacenar la salida (contenido sin procesar, además de pares nombre-valor generados por canalización).Define an index to store the output (raw content, plus pipeline-generated name-value pairs).
  • Ejecute la canalización para iniciar transformaciones y análisis, así como para crear y cargar el índice.Execute the pipeline to start transformations and analysis, and to create and load the index.
  • Explore los resultados mediante la búsqueda de texto completo y una sintaxis de consulta enriquecida.Explore results using full text search and a rich query syntax.

Para completar este tutorial necesitará varios servicios, además de la aplicación de escritorio Postman u otra herramienta de pruebas web para realizar llamadas a la API REST.You'll need several services to complete this walkthrough, plus the Postman desktop app or another Web testing tool to make REST API calls.

Si no tiene una suscripción a Azure, abra una cuenta gratuita antes de empezar.If you don't have an Azure subscription, open a free account before you begin.

Descarga de archivosDownload files

  1. Abra esta carpeta de OneDrive y, en la esquina superior izquierda, haga clic en Descargar para copiar los archivos en el equipo.Open this OneDrive folder and on the top-left corner, click Download to copy the files to your computer.

  2. Haga clic con el botón derecho en el archivo ZIP y seleccione Extraer todo.Right-click the zip file and select Extract All. Hay 14 archivos de varios tipos.There are 14 files of various types. Para este ejercicio, usará 7.You'll use 7 for this exercise.

1: Creación de servicios1 - Create services

En este tutorial se usa Azure Cognitive Search en la indexación y las consultas, Cognitive Services en el enriquecimiento de inteligencia artificial y Azure Blob Storage en la provisión de datos.This walkthrough uses Azure Cognitive Search for indexing and queries, Cognitive Services for AI enrichment, and Azure Blob storage to provide the data. Si es posible, cree los tres servicios en la misma región y grupo de recursos por proximidad y capacidad de administración.If possible, create all three services in the same region and resource group for proximity and manageability. En la práctica, la cuenta de Azure Storage puede estar en cualquier región.In practice, your Azure Storage account can be in any region.

Comienzo con Azure StorageStart with Azure Storage

  1. Inicie sesión en Azure Portal y haga clic en + Crear un recurso.Sign in to the Azure portal and click + Create Resource.

  2. Busque cuenta de almacenamiento y seleccione la oferta de Cuenta de almacenamiento de Microsoft.Search for storage account and select Microsoft's Storage Account offering.

    Creación de una cuenta de almacenamientoCreate Storage account

  3. En la pestaña Datos básicos, se necesitan los siguientes elementos.In the Basics tab, the following items are required. Acepte los valores predeterminados para todo lo demás.Accept the defaults for everything else.

    • Grupo de recursos.Resource group. Seleccione un grupo existente o cree uno nuevo, pero use el mismo grupo para todos los servicios, con el fin de que pueda administrarlos colectivamente.Select an existing one or create a new one, but use the same group for all services so that you can manage them collectively.

    • Nombre de cuenta de almacenamiento.Storage account name. Si cree que puede tener varios recursos del mismo tipo, use el nombre para diferenciarlos por tipo y región, por ejemplo blobstoragewestus.If you think you might have multiple resources of the same type, use the name to disambiguate by type and region, for example blobstoragewestus.

    • Ubicación.Location. Si es posible, elija la misma ubicación que se usa para Azure Cognitive Search y Cognitive Services.If possible, choose the same location used for Azure Cognitive Search and Cognitive Services. Una ubicación única anula los cargos de ancho de banda.A single location voids bandwidth charges.

    • Tipo de cuenta.Account Kind. Elija el valor predeterminado, StorageV2 (uso general v2) .Choose the default, StorageV2 (general purpose v2).

  4. Haga clic en Revisar y crear para crear el servicio.Click Review + Create to create the service.

  5. Una vez creado, haga clic en Go to the resource (Ir al recurso) para abrir la página de información general.Once it's created, click Go to the resource to open the Overview page.

  6. Haga clic en el servicio Blobs.Click Blobs service.

  7. Haga clic en + Contenedor para crear un contenedor y asígnele el nombre cog-search-demo.Click + Container to create a container and name it cog-search-demo.

  8. Seleccione cog-search-demo y haga clic en Cargar para abrir la carpeta en la que guardó los archivos de descarga.Select cog-search-demo and then click Upload to open the folder where you saved the download files. Seleccione todos los archivos que no sean de imagen.Select all of the non-image files. Debería tener 7 archivos.You should have 7 files. Haga clic en Aceptar para empezar a cargar.Click OK to upload.

    Carga de archivos de ejemploUpload sample files

  9. Antes de salir de Azure Storage, obtenga una cadena de conexión para poder formular una conexión en Azure Cognitive Search.Before you leave Azure Storage, get a connection string so that you can formulate a connection in Azure Cognitive Search.

    1. Vuelva a la página de información general de la cuenta de almacenamiento (hemos usado blobstragewestus como ejemplo).Browse back to the Overview page of your storage account (we used blobstragewestus as an example).

    2. En el panel de navegación izquierdo, seleccione Claves de acceso y copie una de las cadenas de conexión.In the left navigation pane, select Access keys and copy one of the connection strings.

    La cadena de conexión es una dirección URL parecida a la del ejemplo siguiente:The connection string is a URL similar to the following example:

    DefaultEndpointsProtocol=https;AccountName=cogsrchdemostorage;AccountKey=<your account key>;EndpointSuffix=core.windows.net
    
  10. Guarde la cadena de conexión en el Bloc de notas.Save the connection string to Notepad. La necesitará más adelante, al configurar la conexión del origen de datos.You'll need it later when setting up the data source connection.

Cognitive ServicesCognitive Services

El enriquecimiento de inteligencia artificial está respaldado por Cognitive Services, lo que incluye Text Analytics y Computer Vision para el procesamiento de imágenes y del lenguaje natural.AI enrichment is backed by Cognitive Services, including Text Analytics and Computer Vision for natural language and image processing. Si su objetivo fuera trabajar con un prototipo o un proyecto reales, en este punto aprovisionaría Cognitive Services (en la misma región que Azure Cognitive Search) para poder conectarlo con las operaciones de indexación.If your objective was to complete an actual prototype or project, you would at this point provision Cognitive Services (in the same region as Azure Cognitive Search) so that you can attach it to indexing operations.

Sin embargo, en este ejercicio puede omitir el aprovisionamiento de recursos, porque Azure Cognitive Search puede conectarse a Cognitive Services en segundo plano y proporcionarle 20 transacciones gratuitas por cada ejecución del indexador.For this exercise, however, you can skip resource provisioning because Azure Cognitive Search can connect to Cognitive Services behind the scenes and give you 20 free transactions per indexer run. Como en este tutorial se usan 7 transacciones, la asignación gratuita es suficiente.Since this tutorial uses 7 transactions, the free allocation is sufficient. En el caso de proyectos mayores, planee aprovisionamiento de Cognitive Services en el nivel S0 de pago por uso.For larger projects, plan on provisioning Cognitive Services at the pay-as-you-go S0 tier. Para más información, consulte Asociación de Cognitive Services.For more information, see Attach Cognitive Services.

El tercer componente es Azure Cognitive Search, que se puede crear en el portal.The third component is Azure Cognitive Search, which you can create in the portal. Puede usar el nivel Gratis para completar este tutorial.You can use the Free tier to complete this walkthrough.

Al igual que con Azure Blob Storage dedique un momento a recopilar la clave de acceso.As with Azure Blob storage, take a moment to collect the access key. Además, cuando empiece a estructurar las solicitudes, deberá proporcionar el punto de conexión y la clave de la API de administración que se usan para autenticar cada solicitud.Further on, when you begin structuring requests, you will need to provide the endpoint and admin api-key used to authenticate each request.

  1. Inicie sesión en Azure Portal y, en la página Información general del servicio de búsqueda, obtenga el nombre del servicio de búsqueda.Sign in to the Azure portal, and in your search service Overview page, get the name of your search service. Para confirmar el nombre del servicio, revise la dirección URL del punto de conexión.You can confirm your service name by reviewing the endpoint URL. Si la dirección URL del punto de conexión fuera https://mydemo.search.windows.net, el nombre del servicio sería mydemo.If your endpoint URL were https://mydemo.search.windows.net, your service name would be mydemo.

  2. En Configuración > Claves, obtenga una clave de administrador para tener derechos completos en el servicio.In Settings > Keys, get an admin key for full rights on the service. Se proporcionan dos claves de administrador intercambiables para lograr la continuidad empresarial, por si necesitara sustituir una de ellas.There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. Puede usar la clave principal o secundaria en las solicitudes para agregar, modificar y eliminar objetos.You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.

    Obtenga también la clave de consulta.Get the query key as well. Es una práctica recomendada emitir solicitudes de consulta con acceso de solo lectura.It's a best practice to issue query requests with read-only access.

Obtención del nombre del servicio y las claves de consulta y administrador

Todas las solicitudes enviadas al servicio necesitan una clave de API en el encabezado.All requests require an api-key in the header of every request sent to your service. Una clave válida genera la confianza, solicitud a solicitud, entre la aplicación que la envía y el servicio que se encarga de ella.A valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

2: Configuración de Postman2 - Set up Postman

Inicie Postman y configure una solicitud HTTP.Start Postman and set up an HTTP request. Si no está familiarizado con esta herramienta, consulte Exploración de las API REST de Azure Cognitive Search mediante Postman.If you are unfamiliar with this tool, see Explore Azure Cognitive Search REST APIs using Postman.

Los métodos de solicitud usados en este tutorial son POST, PUT y GET.The request methods used in this tutorial are POST, PUT, and GET. Usaremos los métodos siguientes para realizar cuatro llamadas API al servicio de búsqueda: crear un origen de datos, un conjunto de aptitudes, un índice y un indexador.You'll use the methods to make four API calls to your search service: create a data source, a skillset, an index, and an indexer.

En Headers (Encabezados), establezca "Content-Type" en application/json y establezca api-key en la clave de API de administración de su servicio Azure Cognitive Search.In Headers, set "Content-type" to application/json and set api-key to the admin api-key of your Azure Cognitive Search service. Una vez que establezca los encabezados, puede usarlos para todas las solicitudes de este ejercicio.Once you set the headers, you can use them for every request in this exercise.

Encabezado y dirección URL de solicitud de PostmanPostman request URL and header

3: Creación de la canalización3 - Create the pipeline

En Azure Cognitive Search, el procesamiento de la inteligencia artificial se produce durante la indexación (o la ingesta de datos).In Azure Cognitive Search, AI processing occurs during indexing (or data ingestion). En esta parte del tutorial se crean cuatro objetos: origen de datos, definición de índice, conjunto de aptitudes, indexador.This part of the walkthrough creates four objects: data source, index definition, skillset, indexer.

Paso 1: Creación de un origen de datosStep 1: Create a data source

Un objeto de origen de datos proporciona la cadena de conexión al contenedor de blobs que contiene los archivos.A data source object provides the connection string to the Blob container containing the files.

  1. Use POST y la dirección URL siguiente, reemplazando NOMBRE-DE-SU-SERVICIO por el nombre real del servicio.Use POST and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service.

    https://[YOUR-SERVICE-NAME].search.windows.net/datasources?api-version=2019-05-06
    
  2. En el cuerpode la solicitud, copie la siguiente definición de JSON y reemplace connectionString por la conexión real de la cuenta de almacenamiento.In request Body, copy the following JSON definition, replacing the connectionString with the actual connection of your storage account.

    No olvide editar también el nombre del contenedor.Remember to edit the container name as well. En un paso anterior sugerimos "cog-search-demo" como nombre del contenedor.We suggested "cog-search-demo" for the container name in an earlier step.

    {
      "name" : "cog-search-demo-ds",
      "description" : "Demo files to demonstrate cognitive search capabilities.",
      "type" : "azureblob",
      "credentials" :
      { "connectionString" :
        "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-ACCOUNT-KEY>;"
      },
      "container" : { "name" : "<YOUR-BLOB-CONTAINER-NAME>" }
    }
    
  3. Envíe la solicitud.Send the request. Debería ver un código de estado 201 que confirme que la operación se ha realizado correctamente.You should see a status code of 201 confirming success.

Si obtuvo un error 403 o 404, compruebe la construcción de la solicitud: api-version=2019-05-06 debe estar en el punto de conexión, api-key debe estar en el encabezado después de Content-Type y su valor debe ser válido para un servicio de búsqueda.If you got a 403 or 404 error, check the request construction: api-version=2019-05-06 should be on the endpoint, api-key should be in the Header after Content-Type, and its value must be valid for a search service. Puede que desee ejecutar el documento JSON a través de un validador JSON en línea para asegurarse de que la sintaxis es correcta.You might want to run the JSON document through an online JSON validator to make sure the syntax is correct.

Paso 2: Creación de un conjunto de aptitudesStep 2: Create a skillset

Un objeto conjunto de aptitudes es un conjunto de pasos de enriquecimiento aplicados al contenido.A skillset object is a set of enrichment steps applied to your content.

  1. Use PUT y la dirección URL siguiente, reemplazando NOMBRE-DE-SU-SERVICIO por el nombre real del servicio.Use PUT and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service.

    https://[YOUR-SERVICE-NAME].search.windows.net/skillsets/cog-search-demo-ss?api-version=2019-05-06
    
  2. En el cuerpode la solicitud, copie la siguiente definición de JSON.In request Body, copy the JSON definition below. Este conjunto de aptitudes consta de las siguientes aptitudes integradas.This skillset consists of the following built-in skills.

    HabilidadSkill DESCRIPCIÓNDescription
    Reconocimiento de entidadesEntity Recognition Extrae los nombres de las personas, organizaciones y ubicaciones del contenido del contenedor de blobs.Extracts the names of people, organizations, and locations from content in the blob container.
    Detección de idiomaLanguage Detection Detecta el idioma del contenido.Detects the content's language.
    División de textoText Split Divide el contenido de gran tamaño en fragmentos más pequeños antes de llamar a la aptitud de extracción de frases clave.Breaks large content into smaller chunks before calling the key phrase extraction skill. La extracción de frases clave acepta entradas de 50 000 caracteres o menos.Key phrase extraction accepts inputs of 50,000 characters or less. Algunos de los archivos de ejemplo deben dividirse para no superar este límite.A few of the sample files need splitting up to fit within this limit.
    Extracción de frases claveKey Phrase Extraction Extrae las principales frases clave.Pulls out the top key phrases.

    Cada aptitud se ejecuta en el contenido del documento.Each skill executes on the content of the document. Durante el procesamiento, Azure Cognitive Search extrae cada documento para leer el contenido de diferentes formatos de archivo.During processing, Azure Cognitive Search cracks each document to read content from different file formats. El texto encontrado procedente del archivo de origen se coloca en un campo content generado, uno para cada documento.Found text originating in the source file is placed into a generated content field, one for each document. Como tal, la entrada pasa a ser "/document/content".As such, the input becomes "/document/content".

    Para la extracción de las frases clave, al usar el separador de texto para dividir los archivos grandes en páginas, el contenido de la aptitud de la extracción de frases clave es "document/pages/*" (para cada página del documento) en lugar de "/document/content".For key phrase extraction, because we use the text splitter skill to break larger files into pages, the context for the key phrase extraction skill is "document/pages/*" (for each page in the document) instead of "/document/content".

    {
      "description": "Extract entities, detect language and extract key-phrases",
      "skills":
      [
        {
          "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
          "categories": [ "Person", "Organization", "Location" ],
          "defaultLanguageCode": "en",
          "inputs": [
            { "name": "text", "source": "/document/content" }
          ],
          "outputs": [
            { "name": "persons", "targetName": "persons" },
            { "name": "organizations", "targetName": "organizations" },
            { "name": "locations", "targetName": "locations" }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
          "inputs": [
            { "name": "text", "source": "/document/content" }
          ],
          "outputs": [
            { "name": "languageCode", "targetName": "languageCode" }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
          "textSplitMode" : "pages",
          "maximumPageLength": 4000,
          "inputs": [
            { "name": "text", "source": "/document/content" },
            { "name": "languageCode", "source": "/document/languageCode" }
          ],
          "outputs": [
            { "name": "textItems", "targetName": "pages" }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
          "context": "/document/pages/*",
          "inputs": [
            { "name": "text", "source": "/document/pages/*" },
            { "name":"languageCode", "source": "/document/languageCode" }
          ],
          "outputs": [
            { "name": "keyPhrases", "targetName": "keyPhrases" }
          ]
        }
      ]
    }
    

    A continuación se muestra una representación gráfica del conjunto de aptitudes.A graphical representation of the skillset is shown below.

    Uso de un conjunto de aptitudesUnderstand a skillset

  3. Envíe la solicitud.Send the request. Postman debe devolver un código de estado 201 que confirme que la operación se ha realizado correctamente.Postman should return a status code of 201 confirming success.

Nota

Las salidas se pueden asignar a un índice, usar como entrada para una aptitud descendente, o ambas cosas como sucede con el código de idioma.Outputs can be mapped to an index, used as input to a downstream skill, or both as is the case with language code. En el índice, un código de idioma es útil para el filtrado.In the index, a language code is useful for filtering. Como entrada, el código de idioma se usa en las aptitudes de análisis de texto para informar a las reglas lingüísticas de la separación de palabras.As an input, language code is used by text analysis skills to inform the linguistic rules around word breaking. Para obtener más información sobre los conceptos básicos del conjunto de aptitudes, consulte el tema sobre la definición de un conjunto de aptitudes.For more information about skillset fundamentals, see How to define a skillset.

Paso 3: Creación de un índiceStep 3: Create an index

Un índice proporciona el esquema que se usa para crear la expresión física del contenido en índices invertidos y otras construcciones en Azure Cognitive Search.An index provides the schema used to create the physical expression of your content in inverted indexes and other constructs in Azure Cognitive Search. El componente más grande de un índice es la colección de campos, donde el tipo de datos y los atributos determinan el contenido y los comportamientos en Azure Cognitive Search.The largest component of an index is the fields collection, where data type and attributes determine contents and behaviors in Azure Cognitive Search.

  1. Use PUT y la dirección URL siguiente, reemplazando NOMBRE-DE-SU-SERVICIO por el nombre real del servicio, para asignar un nombre al índice.Use PUT and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to name your index.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx?api-version=2019-05-06
    
  2. En el cuerpode la solicitud, copie la siguiente definición de JSON.In request Body, copy the following JSON definition. El campo content almacena el propio documento.The content field stores the document itself. Los campos adicionales para languageCode, keyPhrases y organizations representan la nueva información (campos y valores) creada por el conjunto de aptitudes.Additional fields for languageCode, keyPhrases, and organizations represent new information (fields and values) created by the skillset.

    {
      "fields": [
        {
          "name": "id",
          "type": "Edm.String",
          "key": true,
          "searchable": true,
          "filterable": false,
          "facetable": false,
          "sortable": true
        },
        {
          "name": "metadata_storage_name",
          "type": "Edm.String",
          "searchable": false,
          "filterable": false,
          "facetable": false,
          "sortable": false
        },
        {
          "name": "content",
          "type": "Edm.String",
          "sortable": false,
          "searchable": true,
          "filterable": false,
          "facetable": false
        },
        {
          "name": "languageCode",
          "type": "Edm.String",
          "searchable": true,
          "filterable": false,
          "facetable": false
        },
        {
          "name": "keyPhrases",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "filterable": false,
          "facetable": false
        },
        {
          "name": "persons",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "sortable": false,
          "filterable": true,
          "facetable": true
        },
        {
          "name": "organizations",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "sortable": false,
          "filterable": true,
          "facetable": true
        },
        {
          "name": "locations",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "sortable": false,
          "filterable": true,
          "facetable": true
        }
      ]
    }
    
  3. Envíe la solicitud.Send the request. Postman debe devolver un código de estado 201 que confirme que la operación se ha realizado correctamente.Postman should return a status code of 201 confirming success.

Paso 4: Creación y ejecución de un indexadorStep 4: Create and run an indexer

Un indexador rige la canalización.An Indexer drives the pipeline. Los tres componentes que ha creado hasta ahora (origen de datos, conjunto de aptitudes e índice) son entradas para un indexador.The three components you have created thus far (data source, skillset, index) are inputs to an indexer. La creación del indexador en Azure Cognitive Search es el evento que pone toda la canalización en movimiento.Creating the indexer on Azure Cognitive Search is the event that puts the entire pipeline into motion.

  1. Use PUT y la dirección URL siguiente, reemplazando NOMBRE-DE-SU-SERVICIO por el nombre real del servicio, para asignar un nombre al indexador.Use PUT and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to name your indexer.

    https://[servicename].search.windows.net/indexers/cog-search-demo-idxr?api-version=2019-05-06
    
  2. En el cuerpode la solicitud, copie la siguiente definición de JSON.In request Body, copy the JSON definition below. Observe los elementos de asignación de campos; estas asignaciones son importantes porque definen el flujo de datos.Notice the field mapping elements; these mappings are important because they define the data flow.

    fieldMappings se procesa antes que el conjunto de aptitudes y envía el contenido del origen de datos a los campos de destino de un índice.The fieldMappings are processed before the skillset, sending content from the data source to target fields in an index. Usará asignaciones de campos para enviar contenido existente sin modificar al índice.You'll use field mappings to send existing, unmodified content to the index. Si los tipos y nombres de campo son los mismos en ambos extremos, no se requiere ninguna asignación.If field names and types are the same at both ends, no mapping is required.

    outputFieldMappings es para los campos creados por las aptitudes y, por tanto, se procesa después de que se haya ejecutado el conjunto de aptitudes.The outputFieldMappings are for fields created by skills, and thus processed after the skillset has run. Las referencias a sourceFieldNames en outputFieldMappings no existen hasta que el descifrado de documentos o el enriquecimiento las crean.The references to sourceFieldNames in outputFieldMappings don't exist until document cracking or enrichment creates them. targetFieldName es un campo de un índice definido en el esquema del índice.The targetFieldName is a field in an index, defined in the index schema.

    {
      "name":"cog-search-demo-idxr",    
      "dataSourceName" : "cog-search-demo-ds",
      "targetIndexName" : "cog-search-demo-idx",
      "skillsetName" : "cog-search-demo-ss",
      "fieldMappings" : [
        {
          "sourceFieldName" : "metadata_storage_path",
          "targetFieldName" : "id",
          "mappingFunction" :
            { "name" : "base64Encode" }
        },
        {
          "sourceFieldName" : "metadata_storage_name",
          "targetFieldName" : "metadata_storage_name",
          "mappingFunction" :
            { "name" : "base64Encode" }
        },
        {
          "sourceFieldName" : "content",
          "targetFieldName" : "content"
        }
      ],
      "outputFieldMappings" :
      [
        {
          "sourceFieldName" : "/document/persons",
          "targetFieldName" : "persons"
        },
        {
          "sourceFieldName" : "/document/organizations",
          "targetFieldName" : "organizations"
        },
        {
          "sourceFieldName" : "/document/locations",
          "targetFieldName" : "locations"
        },
        {
          "sourceFieldName" : "/document/pages/*/keyPhrases/*",
          "targetFieldName" : "keyPhrases"
        },
        {
          "sourceFieldName": "/document/languageCode",
          "targetFieldName": "languageCode"
        }
      ],
      "parameters":
      {
        "maxFailedItems":-1,
        "maxFailedItemsPerBatch":-1,
        "configuration":
        {
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default",
          "firstLineContainsHeaders": false,
          "delimitedTextDelimiter": ","
        }
      }
    }
    
  3. Envíe la solicitud.Send the request. Postman debe devolver un código de estado 201 que confirme el éxito del procesamiento.Postman should return a status code of 201 confirming successful processing.

    Este paso puede tardar varios minutos en completarse.Expect this step to take several minutes to complete. Aunque el conjunto de datos es pequeño, las aptitudes analíticas realiza un uso intensivo de los recursos.Even though the data set is small, analytical skills are computation-intensive.

Nota

La creación de un indexador invoca la canalización.Creating an indexer invokes the pipeline. Si hay problemas para conectar con los datos, las entradas y salidas de asignación o el orden de las operaciones, se muestran en esta fase.If there are problems reaching the data, mapping inputs and outputs, or order of operations, they appear at this stage. Para volver a ejecutar la canalización con los cambios de código o script, deberá quitar primero los objetos.To re-run the pipeline with code or script changes, you might need to drop objects first. Para más información, consulte Restablecer y volver a ejecutar.For more information, see Reset and re-run.

Acerca de los parámetros de un indexadorAbout indexer parameters

El script establece "maxFailedItems" en -1, que indica al motor de indexación que ignore los errores durante la importación de datos.The script sets "maxFailedItems" to -1, which instructs the indexing engine to ignore errors during data import. Esto es aceptable porque hay muy pocos documentos en el origen de datos de demostración.This is acceptable because there are so few documents in the demo data source. Para un origen de datos mayor, debería establecer un valor mayor que 0.For a larger data source, you would set the value to greater than 0.

La instrucción "dataToExtract":"contentAndMetadata" indica al indexador que extraiga automáticamente el contenido de diferentes formatos de archivo, así como los metadatos relacionados con cada archivo.The "dataToExtract":"contentAndMetadata" statement tells the indexer to automatically extract the content from different file formats as well as metadata related to each file.

Una vez extraído el contenido, puede establecer imageAction para que se extraiga el texto de las imágenes que se encuentran en el origen de datos.When content is extracted, you can set imageAction to extract text from images found in the data source. La configuración de "imageAction":"generateNormalizedImages", en combinación con OCR Skill y Text Merge Skill, le dice al indexador que extraiga texto de las imágenes (por ejemplo, la palabra "stop" de una señal de Stop de tráfico) y lo inserte como parte del campo de contenido.The "imageAction":"generateNormalizedImages" configuration, combined with the OCR Skill and Text Merge Skill, tells the indexer to extract text from the images (for example, the word "stop" from a traffic Stop sign), and embed it as part of the content field. Este comportamiento se aplica a las imágenes incrustadas en los documentos (piense en una imagen de un archivo PDF), así como a las imágenes que se encuentran en el origen de datos, como un archivo JPG.This behavior applies to both the images embedded in the documents (think of an image inside a PDF), as well as images found in the data source, for instance a JPG file.

4: Supervisión de la indexación4 - Monitor indexing

La indexación y el enriquecimiento comienzan en cuanto se envía la solicitud de creación de indexador.Indexing and enrichment commence as soon as you submit the Create Indexer request. En función de las aptitudes cognitivas definidas, la indexación puede tardar un tiempo.Depending on which cognitive skills you defined, indexing can take a while. Para averiguar si el indexador todavía se está ejecutando, envíe la solicitud siguiente para comprobar el estado del indexador.To find out whether the indexer is still running, send the following request to check the indexer status.

  1. Use GET y la dirección URL siguiente, reemplazando NOMBRE-DE-SU-SERVICIO por el nombre real del servicio, para asignar un nombre al indexador.Use GET and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to name your indexer.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexers/cog-search-demo-idxr/status?api-version=2019-05-06
    
  2. Revise la respuesta para saber si el indexador se está ejecutando o para ver la información de los errores y advertencias.Review the response to learn whether the indexer is running, or to view error and warning information.

Si usa el nivel Gratis, se espera el siguiente mensaje: "Could not extract content or metadata from your document.If you are using the Free tier, the following message is expected: `"Could not extract content or metadata from your document. Truncated extracted text to '32768' characters" (No se pudieron extraer el contenido ni los metadatos del documento. El texto extraído se ha truncado a los '32 768' caracteres).Truncated extracted text to '32768' characters". Este mensaje aparece porque la indexación de blobs en el nivel tiene un límite de 32 000 en la extracción de caracteres.This message appears because blob indexing on the Free tier has a32K limit on character extraction. En los niveles superiores no verá este mensaje para este conjunto de datos.You won't see this message for this data set on higher tiers.

Nota

Las advertencias son comunes en algunos escenarios y no siempre indican un problema.Warnings are common in some scenarios and do not always indicate a problem. Por ejemplo, si un contenedor de blobs incluye archivos de imagen y la canalización no controla imágenes, recibirá una advertencia que indica que no se procesaron las imágenes.For example, if a blob container includes image files, and the pipeline doesn't handle images, you'll get a warning stating that images were not processed.

Ahora que ha creado nuevos campos e información, vamos a ejecutar algunas consultas para conocer el valor de la búsqueda cognitiva en lo que se refiere a un escenario de búsqueda típico.Now that you've created new fields and information, let's run some queries to understand the value of cognitive search as it relates to a typical search scenario.

Recuerde que comenzamos con el contenido del blob, donde todo el documento se empaqueta en un solo campo content.Recall that we started with blob content, where the entire document is packaged into a single content field. Puede buscar en este campo elementos que coincidan con sus consultas.You can search this field and find matches to your queries.

  1. Use GET y la siguiente dirección URL, reemplazando NOMBRE-DE-SU-SERVICIO por el nombre real del servicio, para buscar instancias de un término o frase, y devolviendo el campo content y el número de documentos coincidentes.Use GET and the following URL, replacing YOUR-SERVICE-NAME with the actual name of your service, to search for instances of a term or phrase, returning the content field and a count of the matching documents.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx?search=*&$count=true&$select=content?api-version=2019-05-06
    

    Los resultados de esta consulta devuelven el contenido del documento, que es el mismo resultado que obtendría si usara el indexador de blob sin la canalización de búsqueda cognitiva.The results of this query return document contents, which is the same result you would get if used the blob indexer without the cognitive search pipeline. En este campo se pueden realizar búsquedas, pero no se puede trabajar en él si se desean usar facetas, filtros o la función de autocompletar.This field is searchable, but unworkable if you want to use facets, filters, or autocomplete.

    Salida del campo de contenidoContent field output

  2. Para la segunda consulta, devuelva algunos de los nuevos campos que ha creado la canalización (persons, organizations, locations, languageCode).For the second query, return some of the new fields created by the pipeline (persons, organizations, locations, languageCode). Se omite keyPhrases para no extenderse en exceso, pero es preciso incluirlo si se desea ver esos valores.We're omitting keyPhrases for brevity, but you should include it if you want to see those values.

    https://mydemo.search.windows.net/indexes/cog-search-demo-idx/docs?search=*&$count=true&$select=metadata_storage_name,persons,organizations,locations,languageCode&api-version=2019-05-06
    

    Los campos de la instrucción $select contienen información nueva creada a partir de las funcionalidades de procesamiento de lenguaje natural de Cognitive Services.The fields in the $select statement contain new information created from the natural language processing capabilities of Cognitive Services. Como cabría esperar, hay cierto ruido en los resultados y variación entre los documentos, pero en muchos casos, los modelos analíticos generan resultados precisos.As you might expect, there is some noise in the results and variation across documents, but in many instances, the analytical models produce accurate results.

    En la imagen siguiente se muestran los resultados de la carta abierta que escribió Satya Nadella cuando aceptó el puesto de CEO en Microsoft.The following image shows results for Satya Nadella's open letter upon assuming the CEO role at Microsoft.

    Salida de la canalizaciónPipeline output

  3. Para ver cómo puede aprovechar estos campos, agregue un parámetro facet para que se devuelva una agregación de los documentos coincidentes por ubicación.To see how you might take advantage of these fields, add a facet parameter to return an aggregation of matching documents by location.

    https://[YOUR-SERVICE-NAME].search.windows.net/indexes/cog-search-demo-idx/docs?search=*&facet=locations&api-version=2019-05-06
    

    En este ejemplo, para cada ubicación hay 2 o 3 coincidencias.In this example, for each location, there are 2 or 3 matches.

    Salida de facetaFacet output

  4. En este ejemplo final, aplique un filtro a la colección de organizaciones, lo que devolverá dos coincidencias para los criterios de filtro basados en NASDAQ.In this final example, apply a filter on the organizations collection, returning two matches for filter criteria based on NASDAQ.

    cog-search-demo-idx/docs?search=*&$filter=organizations/any(organizations: organizations eq 'NASDAQ')&$select=metadata_storage_name,organizations&$count=true&api-version=2019-05-06
    

Estas consultas muestran algunas de las formas en que puede trabajar con la sintaxis de consulta y los filtros en los nuevos campos creados por la búsqueda cognitiva. Para más ejemplos de consultas, vea Ejemplos de la API REST de búsqueda de documentos, Ejemplos de consulta de sintaxis simple y Ejemplos de consultas que usan la sintaxis de búsqueda de Lucene "completa".These queries illustrate a few of the ways you can work with query syntax and filters on new fields created by cognitive search.For more query examples, see Examples in Search Documents REST API, Simple syntax query examples, and Full Lucene query examples.

Restablecer y volver a ejecutarReset and rerun

En las primeras etapas experimentales del desarrollo de canalizaciones, el enfoque más práctico para las iteraciones de diseño es eliminar los objetos de Azure Cognitive Search y permitir que el código vuelva a generarlos.In the early experimental stages of pipeline development, the most practical approach for design iterations is to delete the objects from Azure Cognitive Search and allow your code to rebuild them. Los nombres de los recursos son únicos.Resource names are unique. La eliminación de un objeto permite volver a crearlo con el mismo nombre.Deleting an object lets you recreate it using the same name.

Para volver a indexar los documentos con las nuevas definiciones:To reindex your documents with the new definitions:

  1. Elimine el indexador, el índice y el conjunto de aptitudes.Delete the indexer, index, and skillset.
  2. Modifique los objetos.Modify objects.
  3. Vuelva a crearlos en el servicio para ejecutar la canalización.Recreate on your service to run the pipeline.

Puede usar el portal para eliminar índices, indexadores y conjuntos de aptitudes, o bien usar DELETE y especificar direcciones URL a cada objeto.You can use the portal to delete indexes, indexers, and skillsets, or use DELETE and provide URLs to each object. El siguiente comando elimina un indexador.The following command deletes an indexer.

DELETE https://[YOUR-SERVICE-NAME]].search.windows.net/indexers/cog-search-demo-idxr?api-version=2019-05-06

Se devuelve el código de estado 204 si la eliminación se realiza correctamente.Status code 204 is returned on successful deletion.

A medida que el código evoluciona, puede refinar una estrategia de regeneración.As your code matures, you might want to refine a rebuild strategy. Para más información, consulte Volver a generar un índice.For more information, see How to rebuild an index.

Puntos claveTakeaways

Este tutorial muestra los pasos básicos para la creación de una canalización de indexación enriquecida a través de la creación de componentes: un origen de datos, un conjunto de aptitudes, un índice y un indexador.This tutorial demonstrates the basic steps for building an enriched indexing pipeline through the creation of component parts: a data source, skillset, index, and indexer.

Se presentaron las aptitudes integradas, junto con la definición del conjunto de aptitudes y los mecanismos de encadenamiento de aptitudes, mediante entradas y salidas.Built-in skills were introduced, along with skillset definition and the mechanics of chaining skills together through inputs and outputs. También aprendió que outputFieldMappings en la definición del indexador es necesario para enrutar los valores enriquecidos de la canalización a un índice que permita búsquedas en un servicio Azure Cognitive Search.You also learned that outputFieldMappings in the indexer definition is required for routing enriched values from the pipeline into a searchable index on an Azure Cognitive Search service.

Por último, ha aprendido cómo probar los resultados y restablecer el sistema para otras iteraciones.Finally, you learned how to test results and reset the system for further iterations. Ha aprendido que emitir consultas en el índice devuelve la salida creada por la canalización de indexación enriquecida.You learned that issuing queries against the index returns the output created by the enriched indexing pipeline.

Limpieza de recursosClean up resources

La manera más rápida de borrar el contenido después de un tutorial es eliminar el grupo de recursos que contenga el servicio de Azure Cognitive Search y Azure Blob service.The fastest way to clean up after a tutorial is by deleting the resource group containing the Azure Cognitive Search service and Azure Blob service. Si decide colocar ambos servicios en el mismo grupo, elimine el grupo de recursos para eliminar de manera permanente todo lo que contiene, incluyendo los servicios y cualquier contenido almacenado que haya creado para este tutorial.Assuming you put both services in the same group, delete the resource group now to permanently delete everything in it, including the services and any stored content that you created for this tutorial. En el portal, el nombre del grupo de recursos está en la página Información general de cada servicio.In the portal, the resource group name is on the Overview page of each service.

Pasos siguientesNext steps

Personalice o extienda la canalización con aptitudes personalizadas.Customize or extend the pipeline with custom skills. Al crear una aptitud personalizada y agregarla a un conjunto de aptitudes, puede incorporar texto o análisis de imágenes que escriba usted mismo.Creating a custom skill and adding it to a skillset allows you to onboard text or image analysis that you write yourself.