REST-Tutorial: Aufrufen von Cognitive Services-APIs in einer Azure Search-IndizierungspipelineREST Tutorial: Call Cognitive Services APIs in an Azure Search indexing pipeline

In diesem Tutorial lernen Sie die Mechanismen des Programmierens von Datenanreicherung in Azure Search mithilfe von kognitiven Qualifikationen kennen.In this tutorial, you learn the mechanics of programming data enrichment in Azure Search using cognitive skills. Qualifikationen werden durch die Verarbeitung von natürlicher Sprache und Bildanalysefunktionen in Cognitive Services unterstützt.Skills are backed by natural language processing (NLP) and image analysis capabilities in Cognitive Services. Durch die Zusammenstellung und Konfiguration von Qualifikationsgruppen können Sie Text und Textdarstellungen eines Bilds oder einer gescannten Dokumentdatei extrahieren.Through skillset composition and configuration, you can extract text and text representations of an image or scanned document file. Sie können außerdem Sprachen, Entitäten, Schlüsselbegriffe und mehr erkennen.You can also detect language, entities, key phrases, and more. Das Endergebnis besteht in reichhaltigen zusätzlichen Inhalten in einem Azure Search-Index, die von einer KI-unterstützten Indizierungspipeline erstellt wurden.The end result is rich additional content in an Azure Search index, created with AI enrichments in an indexing pipeline.

In diesem Tutorial werden Sie die folgenden Aufgaben mithilfe von REST-API-Aufrufen ausführen:In this tutorial, you make REST API calls to perform following tasks:

  • Erstellen einer Indizierungspipeline, die Beispieldaten auf dem Weg in einen Index anreichertCreate an indexing pipeline that enriches sample data in route to an index
  • Anwenden von integrierten Qualifikationen: Entitätserkennung, Spracherkennung, Textbearbeitung und SchlüsselbegriffserkennungApply built-in skills: entity recognition, language detection, text manipulation, key phrase extraction
  • Erfahren Sie, wie Qualifikationen miteinander verkettet werden, indem die Eingänge den Ausgängen in einer Qualifikationsgruppe zugeordnet werdenLearn how to chain skills together by mapping inputs to outputs in a skillset
  • Ausführen von Anforderungen und Überprüfen von ErgebnissenExecute requests and review results
  • Zurücksetzen des Index und der Indexer für die weitere EntwicklungReset the index and indexers for further development

Die Ausgabe ist ein durchsuchbarer Volltextindex auf Azure Search.Output is a full text searchable index on Azure Search. Sie können den Index mit weiteren Standardfunktionen erweitern, wie etwa Synonymen, Bewertungsprofilen, Analysetools und Filtern.You can enhance the index with other standard capabilities, such as synonyms, scoring profiles, analyzers, and filters.

In diesem Tutorial wird der kostenlose Dienst verwendet. Die Anzahl kostenloser Transaktionen ist allerdings auf 20 Dokumente pro Tag beschränkt.This tutorial runs on the Free service, but the number of free transactions is limited to 20 documents per day. Falls Sie dieses Tutorial mehrmals am gleichen Tag ausführen möchten, verwenden Sie einen kleineren Dateisatz, um mehr Ausführungen zu ermöglichen.If you want to run this tutorial more than once in the same day, use a smaller file set so that you can fit in more runs.

Hinweis

Wenn Sie den Umfang erweitern, indem Sie die Verarbeitungsfrequenz erhöhen oder weitere Dokumente oder KI-Algorithmen hinzufügen, müssen Sie eine kostenpflichtige Cognitive Services-Ressource anfügen.As you expand scope by increasing the frequency of processing, adding more documents, or adding more AI algorithms, you will need to attach a billable Cognitive Services resource. Gebühren fallen beim Aufrufen von APIs in Cognitive Services sowie für die Bildextraktion im Rahmen der Dokumentaufschlüsselungsphase in Azure Search an.Charges accrue when calling APIs in Cognitive Services, and for image extraction as part of the document-cracking stage in Azure Search. Für die Textextraktion aus Dokumenten fallen keine Gebühren an.There are no charges for text extraction from documents.

Die Ausführung integrierter Qualifikationen wird nach dem bestehenden nutzungsbasierten Preis für Cognitive Services berechnet.Execution of built-in skills is charged at the existing Cognitive Services pay-as-you go price. Die Preise für die Bildextraktion werden auf der Preisseite von Azure Search beschrieben.Image extraction pricing is described on the Azure Search pricing page.

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.If you don't have an Azure subscription, create a free account before you begin.

VoraussetzungenPrerequisites

In diesem Tutorial werden die folgenden Dienste, Tools und Daten verwendet.The following services, tools, and data are used in this tutorial.

Abrufen eines Schlüssels und einer URLGet a key and URL

Für REST-Aufrufe sind die Dienst-URL und ein Zugriffsschlüssel für jede Anforderung erforderlich.REST calls require the service URL and an access key on every request. Hierfür wird jeweils ein Suchdienst erstellt. Wenn Sie Azure Search also Ihrem Abonnement hinzugefügt haben, können Sie diese Schritte ausführen, um die erforderlichen Informationen zu erhalten:A search service is created with both, so if you added Azure Search to your subscription, follow these steps to get the necessary information:

  1. Melden Sie sich beim Azure-Portal an, und rufen Sie auf der Seite Übersicht Ihres Suchdiensts die URL ab.Sign in to the Azure portal, and in your search service Overview page, get the URL. Ein Beispiel für einen Endpunkt ist https://mydemo.search.windows.net.An example endpoint might look like https://mydemo.search.windows.net.

  2. Rufen Sie unter Einstellungen > Schlüssel einen Administratorschlüssel ab, um Vollzugriff auf den Dienst zu erhalten.In Settings > Keys, get an admin key for full rights on the service. Es gibt zwei austauschbare Administratorschlüssel – diese wurden zum Zweck der Geschäftskontinuität bereitgestellt, falls Sie einen Rollover für einen Schlüssel durchführen müssen.There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. Für Anforderungen zum Hinzufügen, Ändern und Löschen von Objekten können Sie den primären oder den sekundären Schlüssel verwenden.You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.

Abrufen eines HTTP-Endpunkts und ZugriffsschlüsselsGet an HTTP endpoint and access key

Für alle an Ihren Dienst gesendeten Anforderungen ist ein API-Schlüssel erforderlich.All requests require an api-key on every request sent to your service. Ein gültiger Schlüssel stellt anforderungsbasiert eine Vertrauensstellung her zwischen der Anwendung, die die Anforderung versendet, und dem Dienst, der sie verarbeitet.Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

Vorbereiten der BeispieldatenPrepare sample data

Die Anreicherungspipeline lädt per Pull aus Azure-Datenquellen herunter.The enrichment pipeline pulls from Azure data sources. Quelldaten müssen von einem unterstützten Datenquellentyp eines Azure Search-Indexers stammen.Source data must originate from a supported data source type of an Azure Search indexer. Azure Table Storage wird für die kognitive Suche nicht unterstützt.Azure Table Storage is not supported for cognitive search. Für diese Übung verwenden wir Blobspeicher, um verschiedene Inhaltstypen anschaulich vorzustellen.For this exercise, we use blob storage to showcase multiple content types.

  1. Melden Sie sich beim Azure-Portal an, navigieren Sie zu Ihrem Azure-Speicherkonto, klicken Sie auf BLOBs und dann auf + Container.Sign in to the Azure portal, navigate to your Azure storage account, click Blobs, and then click + Container.

  2. Erstellen Sie einen Blobcontainer für die Beispieldaten.Create a Blob container to contain sample data. Sie können die öffentliche Zugriffsebene auf beliebige gültige Werte festlegen.You can set the Public Access Level to any of its valid values.

  3. Öffnen Sie den Container nach der Erstellung, und wählen Sie in der Befehlsleiste die Option Hochladen, um die Beispieldateien hochzuladen, die Sie in einem vorherigen Schritt heruntergeladen haben.After the container is created, open it and select Upload on the command bar to upload the sample files you downloaded in a previous step.

    Quelldateien in Azure Blob Storage

  4. Nachdem die Beispieldateien geladen wurden, rufen Sie den Containernamen und eine Verbindungszeichenfolge für Ihren Blobspeicher ab.After sample files are loaded, get the container name and a connection string for your Blob storage. Dazu können Sie im Azure-Portal zu Ihrem Speicherkonto navigieren.You could do that by navigating to your storage account in the Azure portal. Auf Zugriffsschlüssel, und kopieren Sie dann das Feld Verbindungszeichenfolge.On Access keys, and then copy the Connection String field.

    Bei der Verbindungszeichenfolge sollte es sich um eine URL ähnlich dem folgenden Beispiel handeln:The connection string should be a URL similar to the following example:

    DefaultEndpointsProtocol=https;AccountName=cogsrchdemostorage;AccountKey=<your account key>;EndpointSuffix=core.windows.net
    

Es gibt andere Möglichkeiten zum Angeben der Verbindungszeichenfolge, etwa das Bereitstellen einer Shared Access Signature (SAS).There are other ways to specify the connection string, such as providing a shared access signature. Weitere Informationen über Anmeldeinformationen für Datenquellen finden Sie unter Indizieren von Azure Blob Storage.To learn more about data source credentials, see Indexing Azure Blob Storage.

Einrichten von PostmanSet up Postman

Starten Sie Postman, und richten Sie eine HTTP-Anforderung ein.Start Postman and set up an HTTP request. Wenn Sie mit diesem Tool nicht vertraut sind, lesen Sie Untersuchen von Azure Search-REST-APIs mit Postman oder Fiddler.If you are unfamiliar with this tool, see Explore Azure Search REST APIs using Postman.

Die in diesem Tutorial verwendeten Anforderungsmethoden sind POST, PUT und GET.The request methods used in this tutorial are POST, PUT, and GET. Die Headerschlüssel sind „Content-type“ mit der Einstellung „application/json“ und „api-key“ mit der Einstellung auf einen Administratorschlüssel Ihres Azure Search-Diensts.The header keys are "Content-type" set to "application/json" and an "api-key" set to an admin key of your Azure Search service. Im Text ordnen Sie den eigentlichen Inhalt Ihres Aufrufs an.The body is where you place the actual contents of your call.

Teilweise strukturierte Suche

Wir nutzen Postman zum Senden von vier API-Aufrufen an Ihren Suchdienst, um eine Datenquelle, eine Qualifikationsgruppe, einen Index und einen Indexer zu erstellen.We are using Postman to make four API calls to your search service in order to create a data source, a skillset, an index, and an indexer. Die Datenquelle enthält einen Zeiger auf Ihr Speicherkonto und Ihre JSON-Daten.The data source includes a pointer to your storage account and your JSON data. Ihr Suchdienst stellt die Verbindung beim Laden der Daten her.Your search service makes the connection when loading the data.

Erstellen einer DatenquelleCreate a data source

Jetzt, da Ihre Dienste und Datenquellen vorbereitet sind, beginnen Sie damit, die Komponenten Ihrer Indizierungspipeline zusammenzustellen.Now that your services and source files are prepared, start assembling the components of your indexing pipeline. Beginnen Sie mit einem Datenquellenobjekt, das Azure Search anweist, wie die externen Quelldaten abzurufen sind.Begin with a data source object that tells Azure Search how to retrieve external source data.

Geben Sie im Anforderungsnamen den Dienstnamen, den Sie beim Erstellen des Azure Search-Diensts verwendet haben, und den für Ihren Suchdienst generierten API-Schlüssel an.In the request header, provide the service name you used while creating the Azure Search service, and the api-key generated for your search service. Geben Sie im Hauptteil der Anforderung den Namen des Blobcontainers und die Verbindungszeichenfolge an.In the request body, specify the blob container name and connection string.

Beispiel für eine AnforderungSample Request

POST https://[service name].search.windows.net/datasources?api-version=2019-05-06
Content-Type: application/json
api-key: [admin key]

Syntax des AnforderungstextsRequest Body Syntax

{
  "name" : "demodata",
  "description" : "Demo files to demonstrate cognitive search capabilities.",
  "type" : "azureblob",
  "credentials" :
  { "connectionString" :
    "DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;"
  },
  "container" : { "name" : "<your blob container name>" }
}

Senden Sie die Anforderung.Send the request. Das Web Test-Tool sollte den Erfolg durch Rückgabe von Statuscode 201 bestätigen.The web test tool should return a status code of 201 confirming success.

Da es sich hier um Ihre erste Anforderung handelt, überprüfen Sie im Azure-Portal, ob die Datenquelle in Azure Search erstellt wurde.Since this is your first request, check the Azure portal to confirm the data source was created in Azure Search. Überprüfen Sie auf der Dashboard-Seite des Suchdiensts, ob die Liste „Datenquellen“ einen neuen Eintrag enthält.On the search service dashboard page, verify the Data Sources list has a new item. Möglicherweise müssen Sie einige Minuten warten, bis die Portalseite aktualisiert wurde.You might need to wait a few minutes for the portal page to refresh.

Kachel „Datenquellen“ im PortalData sources tile in the portal

Wenn der Fehler 403 oder 404 angezeigt wird, überprüfen Sie die Konstruktion der Anforderung: api-version=2019-05-06 sollte im Endpunkt vorhanden sein, api-key sollte im Header hinter Content-Type vorhanden sein, und sein Wert muss für einen Suchdienst gültig sein.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. Sie können den Header für die verbleibenden Schritte in diesem Tutorial wiederverwenden.You can reuse the header for the remaining steps in this tutorial.

Erstellen eines SkillsetsCreate a skillset

In diesem Schritt definieren Sie eine Reihe von Anreicherungsschritten, die Sie auf Ihre Daten anwenden möchten.In this step, you define a set of enrichment steps that you want to apply to your data. Jeder Anreicherungsschritt wird als Qualifikation und der Satz von Anreicherungsschritten als Qualifikationsgruppe bezeichnet.You call each enrichment step a skill, and the set of enrichment steps a skillset. In diesem Tutorial werden für die Qualifikationsgruppe integrierte kognitive Qualifikationen verwendet:This tutorial uses built-in cognitive skills for the skillset:

  • Spracherkennung, um die Sprache der Inhalte zu bestimmen.Language Detection to identify the content's language.

  • Text unterteilen, um große Inhalte vor dem Aufrufen der Schlüsselbegriffserkennungs-Qualifikation in kleinere Stücke aufzuteilen.Text Split to break large content into smaller chunks before calling the key phrase extraction skill. Die Schlüsselbegriffserkennung akzeptiert Eingaben von 50.000 Zeichen oder weniger.Key phrase extraction accepts inputs of 50,000 characters or less. Für einige der Beispieldateien ist eine Aufteilung erforderlich, um diesen Grenzwert zu erfüllen.A few of the sample files need splitting up to fit within this limit.

  • Entitätserkennung, um die Namen von Organisationen aus Inhalten im Blobcontainer zu extrahieren.Entity Recognition for extracting the names of organizations from content in the blob container.

  • Schlüsselbegriffserkennung, um die wichtigsten Schlüsselbegriffe herauszuziehen.Key Phrase Extraction to pull out the top key phrases.

Beispiel für eine AnforderungSample Request

Bevor Sie diesen REST-Aufruf ausführen, achten Sie darauf, den Dienstnamen und den Administratorschlüssel in der Anforderung unten zu ersetzen, wenn Ihr Tool den Anforderungsheader beim Wechsel des Aufrufs nicht beibehält.Before you make this REST call, remember to replace the service name and the admin key in the request below if your tool does not preserve the request header between calls.

Mit dieser Anforderung wird eine Qualifikationsgruppe erstellt.This request creates a skillset. Verweisen Sie für den verbleibenden Teil dieses Tutorials auf den Namen der Qualifikationsgruppe demoskillset.Reference the skillset name demoskillset for the rest of this tutorial.

PUT https://[servicename].search.windows.net/skillsets/demoskillset?api-version=2019-05-06
api-key: [admin key]
Content-Type: application/json

Syntax des AnforderungstextsRequest Body Syntax

{
  "description":
  "Extract entities, detect language and extract key-phrases",
  "skills":
  [
    {
      "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text", "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations", "targetName": "organizations"
        }
      ]
    },
    {
      "@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"
        }
      ]
    }
  ]
}

Senden Sie die Anforderung.Send the request. Das Web Test-Tool sollte den Erfolg durch Rückgabe von Statuscode 201 bestätigen.The web test tool should return a status code of 201 confirming success.

Untersuchen des AnforderungstextsExplore the request body

Beachten Sie, in welcher Weise die Schlüsselbegriffserkennungs-Qualifikation für die einzelnen Seiten angewendet wird.Notice how the key phrase extraction skill is applied for each page. Durch Festlegen des Kontexts auf "document/pages/*" führen Sie diesen Anreicherungsschritt für jedes Element des Dokument-/Seitenarrays (für jede Seite im Dokument) aus.By setting the context to "document/pages/*" you run this enricher for each member of the document/pages array (for each page in the document).

Jede Qualifikation wird auf den Inhalten des Dokuments ausgeführt.Each skill executes on the content of the document. Während der Verarbeitung bricht Azure Search jedes Dokument auf, um die Inhalte aus verschiedenen Dateiformaten zu lesen.During processing, Azure Search cracks each document to read content from different file formats. Gefundener Text, der aus der Quelldatei stammt, wird in einem generierten Feld content gespeichert, einem für jedes Dokument.Found text originating in the source file is placed into a generated content field, one for each document. Legen Sie die Eingabe daher auf "/document/content" fest.As such, set the input as "/document/content".

Unten finden Sie eine grafische Darstellung der Qualifikationsgruppe.A graphical representation of the skillset is shown below.

Grundlagen von QualifikationsgruppenUnderstand a skillset

Ausgaben können einem Index zugeordnet, als Eingabe einer Downstream-Qualifikation verwendet oder in beider Weise zugleich eingesetzt werden, wie etwa bei Sprachcode.Outputs can be mapped to an index, used as input to a downstream skill, or both as is the case with language code. Im Index ist ein Sprachcode zu Filterungszwecken nützlich.In the index, a language code is useful for filtering. Als Eingabe wird ein Sprachcode von Qualifikationen zur Textanalyse verwendet, um die Linguistikregeln über Wörtertrennung zu informieren.As an input, language code is used by text analysis skills to inform the linguistic rules around word breaking.

Weitere Informationen zu den Grundlagen von Qualifikationsgruppen finden Sie unter How to define a skillset (Definieren von Qualifikationsgruppen).For more information about skillset fundamentals, see How to define a skillset.

Erstellen eines IndexCreate an index

In diesem Abschnitt definieren Sie das Indexschema, indem Sie angeben, welche Felder in den durchsuchbaren Index aufgenommen und mit welchen Suchattributen die einzelnen Felder versehen werden sollen.In this section, you define the index schema by specifying which fields to include in the searchable index, and the search attributes for each field. Felder besitzen einen Typ und können Attribute annehmen, die bestimmen, wie das Feld verwendet wird (durchsuchbar, sortierbar usw.).Fields have a type and can take attributes that determine how the field is used (searchable, sortable, and so forth). Feldname in einem Index müssen nicht exakt mit den Feldnamen in der Quelle übereinstimmen.Field names in an index are not required to identically match the field names in the source. In einem späteren Schritt fügen Sie in einem Indexer Feldzuordnungen hinzu, um die Quell- und Zielfelder zu verbinden.In a later step, you add field mappings in an indexer to connect source-destination fields. Definieren Sie für diesen Schritt den Index mit Feldbenennungskonventionen, die für Ihre Suchanwendung angemessen sind.For this step, define the index using field naming conventions pertinent to your search application.

In dieser Übung werden die folgenden Felder und Feldtypen verwendet:This exercise uses the following fields and field types:

Feldnamen:field-names: id Inhaltcontent languageCodelanguageCode keyPhraseskeyPhrases organizationsorganizations
field-types:field-types: Edm.StringEdm.String Edm.StringEdm.String Edm.StringEdm.String List<Edm.String>List<Edm.String> List<Edm.String>List<Edm.String>

Beispiel für eine AnforderungSample Request

Bevor Sie diesen REST-Aufruf ausführen, achten Sie darauf, den Dienstnamen und den Administratorschlüssel in der Anforderung unten zu ersetzen, wenn Ihr Tool den Anforderungsheader beim Wechsel des Aufrufs nicht beibehält.Before you make this REST call, remember to replace the service name and the admin key in the request below if your tool does not preserve the request header between calls.

Mit dieser Anforderung wird ein Index erstellt.This request creates an index. Verwenden Sie den Indexnamen demoindex für den verbleibenden Teil dieses Tutorials.Use the index name demoindex for the rest of this tutorial.

PUT https://[servicename].search.windows.net/indexes/demoindex?api-version=2019-05-06
api-key: [api-key]
Content-Type: application/json

Syntax des AnforderungstextsRequest Body Syntax

{
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": true,
      "filterable": false,
      "facetable": false,
      "sortable": true
    },
    {
      "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": "organizations",
      "type": "Collection(Edm.String)",
      "searchable": true,
      "sortable": false,
      "filterable": false,
      "facetable": false
    }
  ]
}

Senden Sie die Anforderung.Send the request. Das Web Test-Tool sollte den Erfolg durch Rückgabe von Statuscode 201 bestätigen.The web test tool should return a status code of 201 confirming success.

Weitere Informationen zum Definieren eines Index finden Sie unter Index erstellen (Azure Search REST-API).To learn more about defining an index, see Create Index (Azure Search REST API).

Erstellen eines Indexers, Zuordnen von Feldern und Ausführen von TransformationenCreate an indexer, map fields, and execute transformations

Bisher haben Sie eine Datenquelle, eine Qualifikationsgruppe und einen Index erstellt.So far you have created a data source, a skillset, and an index. Diese drei Komponenten werden Teil eines Indexers, der jedes einzelne Stück per Pull in einen einzelnen mehrstufigen Vorgang herunterlädt.These three components become part of an indexer that pulls each piece together into a single multi-phased operation. Um diese in einem Indexer zusammenzuführen, müssen Sie Feldzuordnungen definieren.To tie these together in an indexer, you must define field mappings.

  • fieldMappings werden vor der Qualifikationsgruppe verarbeitet, und die Quellfelder der Datenquelle werden Zielfeldern in einem Index zugeordnet.The fieldMappings are processed before the skillset, mapping source fields from the data source to target fields in an index. Wenn die Feldnamen und -typen auf beiden Seiten gleich sind, ist keine Zuordnung erforderlich.If field names and types are the same at both ends, no mapping is required.

  • outputFieldMappings werden nach der Qualifikationsgruppe verarbeitet. Es wird auf nicht vorhandene sourceFieldNames verwiesen, bis diese per Dokumententschlüsselung oder Anreicherung erstellt werden.The outputFieldMappings are processed after the skillset, referencing sourceFieldNames that don't exist until document cracking or enrichment creates them. targetFieldName ist ein Feld in einem Index.The targetFieldName is a field in an index.

Neben dem Verknüpfen von Ein- und Ausgaben können Sie auch Feldzuordnungen nutzen, um Datenstrukturen zu vereinfachen.Besides hooking up inputs to outputs, you can also use field mappings to flatten data structures. Weitere Informationen finden Sie unter Zuordnen angereicherter Felder zu einem durchsuchbaren Index.For more information, see How to map enriched fields to a searchable index.

Beispiel für eine AnforderungSample Request

Bevor Sie diesen REST-Aufruf ausführen, achten Sie darauf, den Dienstnamen und den Administratorschlüssel in der Anforderung unten zu ersetzen, wenn Ihr Tool den Anforderungsheader beim Wechsel des Aufrufs nicht beibehält.Before you make this REST call, remember to replace the service name and the admin key in the request below if your tool does not preserve the request header between calls.

Geben Sie außerdem den Namen Ihres Indexers an.Also, provide the name of your indexer. Sie können auf ihn für den Rest dieses Tutorials als demoindexer verweisen.You can reference it as demoindexer for the rest of this tutorial.

PUT https://[servicename].search.windows.net/indexers/demoindexer?api-version=2019-05-06
api-key: [api-key]
Content-Type: application/json

Syntax des AnforderungstextsRequest Body Syntax

{
  "name":"demoindexer", 
  "dataSourceName" : "demodata",
  "targetIndexName" : "demoindex",
  "skillsetName" : "demoskillset",
  "fieldMappings" : [
    {
      "sourceFieldName" : "metadata_storage_path",
      "targetFieldName" : "id",
      "mappingFunction" :
        { "name" : "base64Encode" }
    },
    {
      "sourceFieldName" : "content",
      "targetFieldName" : "content"
    }
  ],
  "outputFieldMappings" :
  [
    {
      "sourceFieldName" : "/document/organizations",
      "targetFieldName" : "organizations"
    },
    {
      "sourceFieldName" : "/document/pages/*/keyPhrases/*",
      "targetFieldName" : "keyPhrases"
    },
    {
      "sourceFieldName": "/document/languageCode",
      "targetFieldName": "languageCode"
    }
  ],
  "parameters":
  {
    "maxFailedItems":-1,
    "maxFailedItemsPerBatch":-1,
    "configuration":
    {
      "dataToExtract": "contentAndMetadata",
      "imageAction": "generateNormalizedImages"
    }
  }
}

Senden Sie die Anforderung.Send the request. Das Web Test-Tool sollte die erfolgreiche Verarbeitung durch Rückgabe von Statuscode 201 bestätigen.The web test tool should return a status code of 201 confirming successful processing.

Sie sollten damit rechnen, dass die Ausführung dieses Schritts mehrere Minuten in Anspruch nimmt.Expect this step to take several minutes to complete. Das Dataset ist zwar klein, Analysequalifikationen sind aber rechenintensiv.Even though the data set is small, analytical skills are computation-intensive. Einige Qualifikationen, wie etwa die Bildanalyse, weisen lange Ausführungszeiten auf.Some skills, such as image analysis, are long-running.

Tipp

Die Pipeline wird durch Erstellen eines Indexers aufgerufen.Creating an indexer invokes the pipeline. Wenn beim Zugriff auf die Daten, dem Zuordnen von Ein- und Ausgaben oder der Reihenfolge der Vorgänge Probleme bestehen, äußern sie sich in dieser Phase.If there are problems reaching the data, mapping inputs and outputs, or order of operations, they appear at this stage. Um die Pipeline mit Code- oder Skriptänderungen auszuführen, müssen Sie möglicherweise zuerst Objekte löschen.To re-run the pipeline with code or script changes, you might need to drop objects first. Weitere Informationen finden Sie unter Reset and re-run (Zurücksetzen und erneut Ausführen).For more information, see Reset and re-run.

Untersuchen des AnforderungstextsExplore the request body

Das Skript legt "maxFailedItems" auf -1 fest, was die Indexengine anweist, Fehler beim Datenimport zu ignorieren.The script sets "maxFailedItems" to -1, which instructs the indexing engine to ignore errors during data import. Dies ist nützlich, weil die Demodatenquelle nur wenige Dokumente enthält.This is useful because there are so few documents in the demo data source. Für eine größere Datenquelle sollten Sie den Wert größer als 0 festlegen.For a larger data source, you would set the value to greater than 0.

Achten Sie außerdem auf die Anweisung "dataToExtract":"contentAndMetadata" in den Konfigurationsparametern.Also notice the "dataToExtract":"contentAndMetadata" statement in the configuration parameters. Diese Anweisung weist den Indexer an, die Inhalte aus verschiedenen Dateiformaten sowie die den einzelnen Dateien zugeordneten Metadaten automatisch zu extrahieren.This statement tells the indexer to automatically extract the content from different file formats as well as metadata related to each file.

Wenn die Inhalte extrahiert werden, können Sie imageAction darauf festlegen, Text aus in der Datenquelle gefundenen Bildern zu extrahieren.When content is extracted, you can set imageAction to extract text from images found in the data source. Die Konfiguration "imageAction":"generateNormalizedImages" in Kombination mit der OCR- und der Textzusammenführungsqualifikation weist den Indexer an, Text aus den Bildern zu extrahieren (beispielsweise das Wort „Stop“ aus einem Stoppschild) und ihn als Teil des Inhaltsfelds einzubetten.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. Dieses Verhalten betrifft sowohl die in den Dokumenten eingebetteten Bilder (denken Sie etwa an Bilder in PDF-Dateien) als auch die in der Datenquelle gefundenen Bilder, z.B. eine JPG-Datei.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.

Überprüfen des IndexerstatusCheck indexer status

Nachdem der Indexer definiert wurde, wird er automatisch ausgeführt, wenn Sie die Anforderung senden.Once the indexer is defined, it runs automatically when you submit the request. Abhängig von den kognitiven Qualifikationen, die Sie definiert haben, kann die Indizierung länger als erwartet dauern.Depending on which cognitive skills you defined, indexing can take longer than you expect. Um herauszufinden, ob der Indexer noch ausgeführt wird, senden Sie die folgende Anforderung, um den Indexerstatus zu überprüfen.To find out whether the indexer is still running, send the following request to check the indexer status.

GET https://[servicename].search.windows.net/indexers/demoindexer/status?api-version=2019-05-06
api-key: [api-key]
Content-Type: application/json

Aus der Antwort erfahren Sie, ob der Indexer noch ausgeführt wird.The response tells you whether the indexer is running. Verwenden Sie nach dem Abschluss der Indizierung einen weiteren HTTP GET-Aufruf an den STATUS-Endpunkt (wie oben), um Berichte über eventuelle Fehler und Warnungen anzuzeigen, die während der Anreicherung aufgetreten sind.After indexing is finished, use another HTTP GET to the STATUS endpoint (as above) to see reports of any errors and warnings that occurred during enrichment.

Warnungen sind bei bestimmten Kombinationen aus Quelldatei und Qualifikation häufig und weisen nicht immer auf ein Problem hin.Warnings are common with some source file and skill combinations and do not always indicate a problem. Im Rahmen dieses Tutorials sind die Warnungen gutartig (z.B. keine Texteingaben aus den JPEG-Dateien).In this tutorial, the warnings are benign (for example, no text inputs from the JPEG files). Sie können die Statusantwort für ausführliche Informationen über Warnungen überprüfen, die während der Indizierung ausgegeben wurden.You can review the status response for verbose information about warnings emitted during indexing.

Abfragen Ihres IndexQuery your index

Führen Sie nach dem Abschluss der Indizierung Abfragen aus, die die Inhalte einzelner Felder zurückgeben.After indexing is finished, run queries that return the contents of individual fields. Standardmäßig gibt Azure Search die obersten 50 Ergebnisse zurück.By default, Azure Search returns the top 50 results. Die Beispieldaten sind klein, so dass die Standardeinstellung gut funktioniert.The sample data is small so the default works fine. Beim Arbeiten mit größeren Datensets müssen Sie jedoch möglicherweise Parameter in die Abfragezeichenfolge aufnehmen, um mehr Ergebnisse zurückzugeben.However, when working with larger data sets, you might need to include parameters in the query string to return more results. Anweisungen finden Sie unter How to page results in Azure Search (Seitenweise Ausgabe von Ergebnissen in Azure Search).For instructions, see How to page results in Azure Search.

Fragen Sie als Überprüfungsschritt den Index nach allen Feldern ab.As a verification step, query the index for all of the fields.

GET https://[servicename].search.windows.net/indexes/demoindex?api-version=2019-05-06
api-key: [api-key]
Content-Type: application/json

Die Ausgabe ist das Indexschema mit dem Namen, dem Typ und den Attributen für jedes Feld.The output is the index schema, with the name, type, and attributes of each field.

Senden Sie eine zweite Abfrage nach "*", um alle Inhalte eines einzelnen Felds zurückzugeben, z.B. organizations.Submit a second query for "*" to return all contents of a single field, such as organizations.

GET https://[servicename].search.windows.net/indexes/demoindex/docs?search=*&$select=organizations&api-version=2019-05-06
api-key: [api-key]
Content-Type: application/json

Wiederholen Sie das Verfahren in dieser Übung für weitere Felder: „content“, „languageCode“, „keyPhrases“ und „organizations“.Repeat for additional fields: content, languageCode, keyPhrases, and organizations in this exercise. Mithilfe von $select können Sie unter Einsatz einer durch Trennzeichen getrennten Liste mehrere Felder zurückgeben.You can return multiple fields via $select using a comma-delimited list.

Sie können GET oder POST verwenden, abhängig von der Komplexität und Länge der Abfragezeichenfolge.You can use GET or POST, depending on query string complexity and length. Weitere Informationen finden Sie unter Abfragen mithilfe der REST-API.For more information, see Query using the REST API.

Zurücksetzen und erneut ausführenReset and rerun

In den frühen, experimentellen Phasen der Pipelineentwicklung besteht der praktikabelste Ansatz für den Übergang von einer Entwurfsphase zur nächsten darin, die Objekt aus Azure Search zu löschen und Ihrem Code zu erlauben, sie neu zu erstellen.In the early experimental stages of pipeline development, the most practical approach for design iterations is to delete the objects from Azure Search and allow your code to rebuild them. Ressourcennamen sind eindeutig.Resource names are unique. Wenn Sie ein Objekt löschen, können Sie es unter dem gleichen Namen neu erstellen.Deleting an object lets you recreate it using the same name.

So indizieren Sie Ihre Dokumente mit den neuen Definitionen erneut:To reindex your documents with the new definitions:

  1. Löschen Sie den Index, um persistente Daten zu entfernen.Delete the index to remove persisted data. Löschen Sie den Indexer, um ihn für Ihren Dienst neu zu erstellen.Delete the indexer to recreate it on your service.
  2. Ändern Sie eine Qualifikationsgruppe und die Indexdefinition.Modify a skillset and index definition.
  3. Führen Sie eine Neuerstellung eines Index und des Indexers für den Dienst aus, um die Pipeline auszuführen.Recreate an index and indexer on the service to run the pipeline.

Sie können das Portal verwenden, um Indizes, Indexer und Qualifikationsgruppen zu löschen.You can use the portal to delete indexes, indexers, and Skillsets.

DELETE https://[servicename].search.windows.net/skillsets/demoskillset?api-version=2019-05-06
api-key: [api-key]
Content-Type: application/json

Nach erfolgreichem Löschen wird der Statuscode 204 zurückgegeben.Status code 204 is returned on successful deletion.

In dem Maß, da Ihr Code reift, kann es sinnvoll sein, die Neuerstellungsstrategie neu zu definieren.As your code matures, you might want to refine a rebuild strategy. Weitere Informationen finden Sie unter Neuerstellen eines Indexes.For more information, see How to rebuild an index.

Wesentliche PunkteTakeaways

Dieses Tutorial veranschaulicht die grundlegenden Schritte beim Erstellen einer erweiterten Indizierungspipeline durch Erstellung von Komponenten: eine Datenquelle, eine Qualifikationsgruppe, ein Index und ein Indexer.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.

Es wurden vordefinierte Qualifikationen im Zusammenhang mit der Qualifikationsgruppendefinition und den Mechanismen zum Verketten von Qualifikationen mithilfe von Eingängen und Ausgängen vorgestellt.Predefined skills were introduced, along with skillset definition and the mechanics of chaining skills together through inputs and outputs. Sie haben darüber hinaus erfahren, dass outputFieldMappings in der Indexerdefinition erforderlich ist, um angereicherte Werte aus der Pipeline in einen durchsuchbaren Index in einem Azure Search-Dienst weiterzuleiten.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 Search service.

Ferner haben Sie erfahren, wie die Ergebnisse getestet werden und das System für weitere Entwicklungsschritte zurückgesetzt wird.Finally, you learned how to test results and reset the system for further iterations. Sie haben gelernt, dass das Ausgeben von Abfragen auf den Index die von der angereicherten Indizierungspipeline erstellte Ausgabe zurückgibt.You learned that issuing queries against the index returns the output created by the enriched indexing pipeline. In dieser Version ist ein Mechanismus zum Anzeigen von internen Konstrukten (vom System erstellten angereicherten Dokumenten) verfügbar.In this release, there is a mechanism for viewing internal constructs (enriched documents created by the system). Darüber hinaus haben Sie die Überprüfung des Indexerstatus und das Löschen von Objekten vor der erneuten Ausführung einer Pipeline gelernt.You also learned how to check indexer status, and which objects to delete before rerunning a pipeline.

Bereinigen von RessourcenClean up resources

Die schnellste Möglichkeit, das System nach einem Tutorial aufzuräumen, besteht im Löschen der Ressourcengruppe, die den Azure Search-Dienst und den Azure Blob-Dienst enthält.The fastest way to clean up after a tutorial is by deleting the resource group containing the Azure Search service and Azure Blob service. Unter der Annahme, dass Sie beide Dienste in der gleichen Gruppe platziert haben, löschen Sie nun einfach die Ressourcengruppe, um endgültig ihren gesamten Inhalt zu löschen, einschließlich der Dienste und aller gespeicherten Inhalte, die Sie für dieses Tutorial erstellt haben.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. Im Portal finden Sie den Namen der Ressourcengruppe auf der Seite „Übersicht“ der einzelnen Dienste.In the portal, the resource group name is on the Overview page of each service.

Nächste SchritteNext steps

Anpassen oder Erweitern der Pipeline mit benutzerdefinierten Qualifikationen.Customize or extend the pipeline with custom skills. Das Erstellen einer benutzerdefinierten Qualifikation die Sie einer Qualifikationsgruppe hinzufügen, ermöglicht Ihnen, eigene, von Ihnen selbst erstellte Text- oder Bildanalysen einzubeziehen.Creating a custom skill and adding it to a skillset allows you to onboard text or image analysis that you write yourself.