Öğretici: REST API 'Leri kullanarak Azure 'da JSON Bloblarından metin ve yapı ayıklama (Azure Bilişsel Arama)Tutorial: Extract text and structure from JSON blobs in Azure using REST APIs (Azure Cognitive Search)

Azure Blob depolamada yapılandırılmamış metin veya görüntü içeriğiniz varsa, bir AI zenginleştirme işlem hattı , tam metin arama veya bilgi araştırma senaryoları için faydalı olan bilgileri ayıklamanızı ve yeni içerik oluşturmanıza yardımcı olabilir.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. İşlem hattı görüntü dosyalarını (JPG, PNG, TIFF) işleyebilse de, bu öğretici Word tabanlı içeriğe odaklanmasına karşın sorgularda, modellerde ve filtrelerde kullanabileceğiniz yeni alanlar ve bilgiler oluşturmak için dil algılamayı ve metin analizlerini uygular.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.

  • Azure Blob depolamada PDF, MD, DOCX ve PPTX gibi tüm belgeler (yapılandırılmamış metin) ile başlayın.Start with whole documents (unstructured text) such as PDF, MD, DOCX, and PPTX in Azure Blob storage.
  • Metin çıkaran, dili algılayan, varlıkları tanıyan ve anahtar tümceleri algılayan bir işlem hattı tanımlayın.Define a pipeline that extracts text, detects language, recognizes entities, and detects key phrases.
  • Çıktıyı depolamak için bir dizin tanımlayın (ham içerik ve ardışık düzen tarafından oluşturulan ad-değer çiftleri).Define an index to store the output (raw content, plus pipeline-generated name-value pairs).
  • Dönüşümleri ve Analizi başlatmak ve dizini oluşturmak ve yüklemek için işlem hattını yürütün.Execute the pipeline to start transformations and analysis, and to create and load the index.
  • Tam metin aramasını ve zengin sorgu söz dizimini kullanarak sonuçları keşfedebilirsiniz.Explore results using full text search and a rich query syntax.

Bu izlenecek yolu tamamlamak için birkaç hizmete, Ayrıca, REST API çağrısı yapmak için Postman masaüstü uygulamasını veya başka bir Web Testi aracını kullanmanız gerekir.You'll need several services to complete this walkthrough, plus the Postman desktop app or another Web testing tool to make REST API calls.

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap açın.If you don't have an Azure subscription, open a free account before you begin.

Dosyaları indirmeDownload files

  1. Bu OneDrive klasörünü açın ve sol üst köşedeki dosyaları bilgisayarınıza kopyalamak için İndir ' e tıklayın.Open this OneDrive folder and on the top-left corner, click Download to copy the files to your computer.

  2. ZIP dosyasına sağ tıklayın ve Tümünü Ayıkla' yı seçin.Right-click the zip file and select Extract All. Çeşitli türlerde 14 dosya vardır.There are 14 files of various types. Bu alıştırma için 7 kullanacaksınız.You'll use 7 for this exercise.

1-hizmet oluşturma1 - Create services

Bu kılavuzda, verileri sağlamak üzere dizin oluşturma ve sorgular, AI zenginleştirme için bilişsel hizmetler ve Azure Blob depolama için Azure Bilişsel Arama kullanılmaktadır.This walkthrough uses Azure Cognitive Search for indexing and queries, Cognitive Services for AI enrichment, and Azure Blob storage to provide the data. Mümkünse, yakınlık ve yönetilebilirlik için aynı bölgedeki ve kaynak grubundaki tüm üç hizmeti oluşturun.If possible, create all three services in the same region and resource group for proximity and manageability. Uygulamada, Azure depolama hesabınız herhangi bir bölgede olabilir.In practice, your Azure Storage account can be in any region.

Azure Storage 'ı kullanmaya başlamaStart with Azure Storage

  1. Azure Portal oturum açın ve + kaynak oluştur' a tıklayın.Sign in to the Azure portal and click + Create Resource.

  2. Depolama hesabı araması yapın ve Microsoft 'un depolama hesabı teklifi ' ni seçin.Search for storage account and select Microsoft's Storage Account offering.

    Depolama hesabı oluşturCreate Storage account

  3. Temel bilgiler sekmesinde, aşağıdaki öğeler gereklidir.In the Basics tab, the following items are required. Diğer her şey için varsayılanları kabul edin.Accept the defaults for everything else.

    • Kaynak grubu.Resource group. Mevcut bir tane seçin veya yeni bir tane oluşturun, ancak bunları topluca yönetebilmeniz için tüm hizmetler için aynı grubu kullanın.Select an existing one or create a new one, but use the same group for all services so that you can manage them collectively.

    • Depolama hesabı adı.Storage account name. Aynı türde birden fazla kaynağınız olabileceğini düşünüyorsanız, tür ve bölgeye göre belirsizliği ortadan kaldırmak için adı kullanın, örneğin 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.

    • Konum.Location. Mümkünse, Azure Bilişsel Arama ve bilişsel hizmetler için kullanılan aynı konumu seçin.If possible, choose the same location used for Azure Cognitive Search and Cognitive Services. Tek bir konum, bant genişliği ücretlerini oylar.A single location voids bandwidth charges.

    • Hesap türü.Account Kind. Varsayılan, StorageV2 (genel amaçlı v2) seçeneğini belirleyin.Choose the default, StorageV2 (general purpose v2).

  4. Hizmeti oluşturmak için gözden geçir + oluştur ' a tıklayın.Click Review + Create to create the service.

  5. Oluşturulduktan sonra genel bakış sayfasını açmak için Kaynağa Git ' e tıklayın.Once it's created, click Go to the resource to open the Overview page.

  6. Bloblar hizmeti ' ne tıklayın.Click Blobs service.

  7. Bir kapsayıcı oluşturmak ve COG-Search-demoolarak adlandırmak Için + kapsayıcı ' ya tıklayın.Click + Container to create a container and name it cog-search-demo.

  8. COG-Search-demo ' i seçin ve ardından yükleme dosyalarını kaydettiğiniz klasörü açmak Için karşıya yükle ' ye tıklayın.Select cog-search-demo and then click Upload to open the folder where you saved the download files. Görüntü olmayan dosyaların tümünü seçin.Select all of the non-image files. 7 dosyasına sahip olmanız gerekir.You should have 7 files. Karşıya yüklemek için Tamam 'ı tıklatın.Click OK to upload.

    Örnek dosyaları karşıya yükleUpload sample files

  9. Azure depolama alanını kapatmadan önce Azure Bilişsel Arama bir bağlantıyı formülleştirmek için bir bağlantı dizesi alın.Before you leave Azure Storage, get a connection string so that you can formulate a connection in Azure Cognitive Search.

    1. Depolama hesabınızın genel bakış sayfasına geri gidin (örnek olarak blobstragewestus kullandık).Browse back to the Overview page of your storage account (we used blobstragewestus as an example).

    2. Sol gezinti bölmesinde erişim anahtarları ' nı seçin ve bağlantı dizelerinden birini kopyalayın.In the left navigation pane, select Access keys and copy one of the connection strings.

    Bağlantı dizesi, aşağıdaki örneğe benzer bir URL 'dir:The connection string is a URL similar to the following example:

    DefaultEndpointsProtocol=https;AccountName=cogsrchdemostorage;AccountKey=<your account key>;EndpointSuffix=core.windows.net
    
  10. Bağlantı dizesini Not defteri 'ne kaydedin.Save the connection string to Notepad. Daha sonra veri kaynağı bağlantısını ayarlarken gerekecektir.You'll need it later when setting up the data source connection.

Bilişsel HizmetlerCognitive Services

AI zenginleştirme, doğal dil ve görüntü işleme için Metin Analizi ve Görüntü İşleme dahil bilişsel hizmetler tarafından desteklenir.AI enrichment is backed by Cognitive Services, including Text Analytics and Computer Vision for natural language and image processing. Amacınız gerçek bir prototipi veya projeyi tamamlayacaksa, bu noktada bilişsel hizmetler sağlama (Azure Bilişsel Arama ile aynı bölgede), böylece dizin oluşturma işlemlerine iliştirebilirsiniz.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.

Bununla birlikte, Azure Bilişsel Arama, arka planda bilişsel hizmetlere bağlanıp Dizin Oluşturucu başına 20 ücretsiz işlem sunabileceğinden kaynak sağlamayı atlayabilirsiniz.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. Bu öğretici 7 işlem kullandığından, ücretsiz ayırma yeterlidir.Since this tutorial uses 7 transactions, the free allocation is sufficient. Daha büyük projeler için, Kullandıkça öde, bu hizmetleri, Kullandıkça öde, bu hizmetler için sağlama bölümüne planlayın.For larger projects, plan on provisioning Cognitive Services at the pay-as-you-go S0 tier. Daha fazla bilgi için bkz. bilişsel Hizmetler iliştirme.For more information, see Attach Cognitive Services.

Üçüncü bileşen, portalda oluşturabileceğinizAzure bilişsel arama.The third component is Azure Cognitive Search, which you can create in the portal. Bu izlenecek yolu tamamlamak için ücretsiz katmanı kullanabilirsiniz.You can use the Free tier to complete this walkthrough.

Azure Blob depolamada olduğu gibi, erişim anahtarını toplamak için biraz zaman ayırın.As with Azure Blob storage, take a moment to collect the access key. Ayrıca, istekleri raporlamaya başladığınızda, her bir isteğin kimliğini doğrulamak için kullanılan uç nokta ve yönetici API 'si anahtarını sağlamanız gerekir.Further on, when you begin structuring requests, you will need to provide the endpoint and admin api-key used to authenticate each request.

  1. Azure Portal oturum açınve arama hizmetinize genel bakış sayfasında, arama hizmetinizin adını alın.Sign in to the Azure portal, and in your search service Overview page, get the name of your search service. Uç nokta URL 'sini inceleyerek hizmet adınızı doğrulayabilirsiniz.You can confirm your service name by reviewing the endpoint URL. Uç nokta URL 'niz https://mydemo.search.windows.net, hizmet adınız mydemoolur.If your endpoint URL were https://mydemo.search.windows.net, your service name would be mydemo.

  2. Ayarlar > anahtarlar' da, hizmette tam haklar için bir yönetici anahtarı alın.In Settings > Keys, get an admin key for full rights on the service. Üzerinde bir tane almanız gereken iş sürekliliği için iki adet değiştirilebilir yönetici anahtarı vardır.There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. Nesneleri eklemek, değiştirmek ve silmek için isteklerde birincil veya ikincil anahtarı kullanabilirsiniz.You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.

    Sorgu anahtarını da alın.Get the query key as well. Salt okuma erişimiyle sorgu istekleri vermek en iyi uygulamadır.It's a best practice to issue query requests with read-only access.

Hizmet adı ve yönetici ve sorgu anahtarlarını alın

Tüm istekler, hizmetinize gönderilen her isteğin üstbilgisinde bir API anahtarı gerektirir.All requests require an api-key in the header of every request sent to your service. Geçerli bir anahtar, istek başına, isteği gönderen uygulama ve onu işleyen hizmet arasında güven oluşturur.A valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

2-Postman 'ı ayarlama2 - Set up Postman

Postman’i başlatın ve bir HTTP isteği ayarlayın.Start Postman and set up an HTTP request. Bu aracı hakkında bilginiz varsa bkz. Postman kullanarak Azure BILIŞSEL arama REST API 'Lerini araştırma.If you are unfamiliar with this tool, see Explore Azure Cognitive Search REST APIs using Postman.

Bu öğreticide kullanılan istek metotları gönderi, PUTve Get.The request methods used in this tutorial are POST, PUT, and GET. Arama hizmetinize dört API çağrısı yapmak için yöntemlerini kullanacaksınız: bir veri kaynağı, bir beceri, dizin ve Dizin Oluşturucu oluşturun.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.

Üst bilgilerde, "Content-Type" öğesini application/json olarak ayarlayın ve api-key Azure Bilişsel Arama hizmetinizin Yönetici API 'si anahtarına ayarlayın.In Headers, set "Content-type" to application/json and set api-key to the admin api-key of your Azure Cognitive Search service. Üst bilgileri ayarladıktan sonra bu alýþtýrmadaki her istek için kullanabilirsiniz.Once you set the headers, you can use them for every request in this exercise.

Postman istek URL 'SI ve üstbilgisiPostman request URL and header

3-işlem hattını oluşturma3 - Create the pipeline

Azure Bilişsel Arama 'de, dizin oluşturma (veya veri alımı) sırasında AI işleme oluşur.In Azure Cognitive Search, AI processing occurs during indexing (or data ingestion). İzlenecek yolun bu bölümü dört nesne oluşturur: veri kaynağı, Dizin tanımı, Beceri, Dizin Oluşturucu.This part of the walkthrough creates four objects: data source, index definition, skillset, indexer.

1. Adım: Veri kaynağı oluşturmaStep 1: Create a data source

Veri kaynağı nesnesi , dosyaları içeren blob kapsayıcısına bağlantı dizesi sağlar.A data source object provides the connection string to the Blob container containing the files.

  1. Post 'u ve aşağıdaki URL 'yi kullanarak hizmet adını hizmetinizin gerçek adıyla değiştirin.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. İstek gövdesi' nde aşağıdaki JSON tanımını kopyalayın ve connectionString, depolama hesabınızın gerçek bağlantısıyla değiştirin.In request Body, copy the following JSON definition, replacing the connectionString with the actual connection of your storage account.

    Kapsayıcı adını da düzenlemeyi unutmayın.Remember to edit the container name as well. Önceki bir adımda kapsayıcı adı için "COG-Search-demo" önerilir.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. İsteği gönderin.Send the request. Başarıyı onaylayan 201 durum kodunu görmeniz gerekir.You should see a status code of 201 confirming success.

Bir 403 veya 404 hatası aldıysanız, istek yapısını denetleyin: api-version=2019-05-06, uç nokta üzerinde olmalıdır, api-key, Üst bilgide Content-Type öğesinden sonra gelmelidir ve değeri bir arama hizmeti için geçerli olmalıdır.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. Sözdiziminin doğru olduğundan emin olmak için JSON belgesini çevrimiçi bir JSON doğrulayıcısı aracılığıyla çalıştırmak isteyebilirsiniz.You might want to run the JSON document through an online JSON validator to make sure the syntax is correct.

2. Adım: beceri oluşturmaStep 2: Create a skillset

Beceri nesnesi , içeriğinize uygulanan bir zenginleştirme adımları kümesidir.A skillset object is a set of enrichment steps applied to your content.

  1. PUT ve aşağıdaki URL 'yi kullanın ve hizmet adını hizmetinizin gerçek adıyla değiştirin.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. İstek gövdesi' nde, aşağıdaki JSON tanımını kopyalayın.In request Body, copy the JSON definition below. Bu beceri, aşağıdaki yerleşik becerilerden oluşur.This skillset consists of the following built-in skills.

    İmdeSkill AçıklamaDescription
    Varlık tanımaEntity Recognition Kişilerin, kuruluşların ve konumların adlarını blob kapsayıcısındaki içerikten ayıklar.Extracts the names of people, organizations, and locations from content in the blob container.
    Dil algılamaLanguage Detection İçeriğin dilini algılar.Detects the content's language.
    Metin bölmeText Split Anahtar tümceciği ayıklama becerisi çağrılmadan önce büyük içeriği daha küçük parçalara ayırır.Breaks large content into smaller chunks before calling the key phrase extraction skill. Anahtar tümcecik ayıklama, 50.000 veya daha az karakterden oluşan girişi kabul eder.Key phrase extraction accepts inputs of 50,000 characters or less. Bu sınıra uymak için örnek dosyaların birkaç tanesinin bölünmesi gerekir.A few of the sample files need splitting up to fit within this limit.
    Anahtar ifade ayıklamaKey Phrase Extraction En üstteki anahtar tümceleri çeker.Pulls out the top key phrases.

    Her beceri, belge içeriğinde yürütülür.Each skill executes on the content of the document. İşlem sırasında Azure Bilişsel Arama, farklı dosya biçimlerinden içerik okumak için her belgeyi ister.During processing, Azure Cognitive Search cracks each document to read content from different file formats. Kaynak dosyadan gelen, bulunan metin, oluşturulan content alanına her belge için birer birer yerleştirilir.Found text originating in the source file is placed into a generated content field, one for each document. Bu nedenle, giriş "/document/content"olur.As such, the input becomes "/document/content".

    Anahtar tümceciği ayıklama için, büyük dosyaları sayfalara bölmek üzere metin Bölümlendirici yeteneği kullandığımızda, anahtar tümceciği ayıklama becerinin bağlamı "/document/content"yerine "document/pages/*" (belgedeki her sayfa için).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" }
          ]
        }
      ]
    }
    

    Beceri kümesinin grafiksel gösterimi aşağıda gösterilmektedir.A graphical representation of the skillset is shown below.

    Beceri anlayınUnderstand a skillset

  3. İsteği gönderin.Send the request. Postman, başarıyı onaylayan 201 durum kodunu döndürmelidir.Postman should return a status code of 201 confirming success.

Not

Çıktılar bir dizine eşlenebilir, aşağı akış becerisine yönelik giriş olarak kullanılır veya dil kodunda olduğu gibi her iki şekilde de kullanılabilir.Outputs can be mapped to an index, used as input to a downstream skill, or both as is the case with language code. Dizinde bir dil kodu, filtreleme için yararlıdır.In the index, a language code is useful for filtering. Giriş olarak dil kodu, sözcük bölünmesiyle ilgili dilbilgisi kurallarını bildirmek için metin analizi becerileri tarafından kullanılır.As an input, language code is used by text analysis skills to inform the linguistic rules around word breaking. Beceri kümesi temelleri hakkında daha fazla bilgi için bkz. Beceri kümesini tanımlama.For more information about skillset fundamentals, see How to define a skillset.

3. Adım: Dizin oluşturmaStep 3: Create an index

Bir Dizin , içeriğinizin fiziksel ifadesini, ters dizinler ve Azure bilişsel arama diğer yapıları oluşturmak için kullanılan şemayı sağlar.An index provides the schema used to create the physical expression of your content in inverted indexes and other constructs in Azure Cognitive Search. Bir dizinin en büyük bileşeni, veri türü ve özniteliklerin Azure Bilişsel Arama 'daki içerikleri ve davranışları belirlerken alanlar koleksiyonudur.The largest component of an index is the fields collection, where data type and attributes determine contents and behaviors in Azure Cognitive Search.

  1. Dizininizi adlandırmak için, PUT ve aşağıdaki URL 'yi kullanarak hizmet adınızı hizmetinizin gerçek adıyla değiştirin.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. İstek gövdesi' nde aşağıdaki JSON tanımını kopyalayın.In request Body, copy the following JSON definition. content alanı belgenin kendisini depolar.The content field stores the document itself. languageCode, keyPhrasesve organizations için ek alanlar, beceri tarafından oluşturulan yeni bilgileri (alanlar ve değerler) temsil eder.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. İsteği gönderin.Send the request. Postman, başarıyı onaylayan 201 durum kodunu döndürmelidir.Postman should return a status code of 201 confirming success.

4. Adım: Dizin Oluşturucu oluşturma ve çalıştırmaStep 4: Create and run an indexer

Dizin Oluşturucu , işlem hattını sürücüler.An Indexer drives the pipeline. Şimdiye kadar oluşturduğunuz üç bileşen (veri kaynağı, Beceri, dizin) bir dizin oluşturucunun girdileri olur.The three components you have created thus far (data source, skillset, index) are inputs to an indexer. Azure Bilişsel Arama dizin oluşturucunun oluşturulması, tüm işlem hattının hareket halinde yer aldığı olaydır.Creating the indexer on Azure Cognitive Search is the event that puts the entire pipeline into motion.

  1. Dizin oluşturucuyu adlandırmak için PUT ve aşağıdaki URL 'yi kullanın ve hizmet adını hizmetinizin gerçek adıyla değiştirin.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. İstek gövdesi' nde, aşağıdaki JSON tanımını kopyalayın.In request Body, copy the JSON definition below. Alan eşleme öğelerine dikkat edin; Bu eşlemeler veri akışını tanımladıklarından önemlidir.Notice the field mapping elements; these mappings are important because they define the data flow.

    fieldMappings, bir dizindeki hedef alanlara veri kaynağından içerik gönderen beceri önce işlenir.The fieldMappings are processed before the skillset, sending content from the data source to target fields in an index. Dizine var olan, değiştirilmemiş içeriği göndermek için alan eşlemelerini kullanacaksınız.You'll use field mappings to send existing, unmodified content to the index. Alan adları ve türleri her iki uçta da aynıysa, hiçbir eşleme gerekmez.If field names and types are the same at both ends, no mapping is required.

    outputFieldMappings yetenekler tarafından oluşturulan alanlara yöneliktir ve bu nedenle beceri çalıştıktan sonra işlenir.The outputFieldMappings are for fields created by skills, and thus processed after the skillset has run. Belge çözme veya zenginleştirme onları oluşturuncaya kadar outputFieldMappings sourceFieldNames başvuruları yok.The references to sourceFieldNames in outputFieldMappings don't exist until document cracking or enrichment creates them. targetFieldName dizin şemasında tanımlanan, dizin içindeki bir alandır.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. İsteği gönderin.Send the request. Postman, başarılı işlemeyi onaylayan 201 durum kodunu döndürmelidir.Postman should return a status code of 201 confirming successful processing.

    Bu adımın tamamlanması birkaç dakika sürebilir.Expect this step to take several minutes to complete. Veri kümesi küçük olsa da, analiz becerileri bilgi işlem açısından yoğundur.Even though the data set is small, analytical skills are computation-intensive.

Not

Bir dizin oluşturucu oluşturulduğunda, işlem hattı çağrılır.Creating an indexer invokes the pipeline. Verilere ulaşılırken, eşleme girişleri ve çıktıları veya işlemlerin sırası ile ilgili sorun olursa bunlar bu aşamada görüntülenir.If there are problems reaching the data, mapping inputs and outputs, or order of operations, they appear at this stage. İşlem hattını, kod veya betik değişiklikleriyle yeniden çalıştırmak için önce nesneleri bırakmanız gerekebilir.To re-run the pipeline with code or script changes, you might need to drop objects first. Daha fazla bilgi için bkz. Sıfırlama ve yeniden çalıştırma.For more information, see Reset and re-run.

Dizin Oluşturucu parametreleri hakkındaAbout indexer parameters

Betik, "maxFailedItems" değerini -1 olarak ayarlayarak dizin oluşturma motoruna, veri içeri aktarma sırasında hataları yoksaymasını bildirir.The script sets "maxFailedItems" to -1, which instructs the indexing engine to ignore errors during data import. Bu, tanıtım verileri kaynağında çok az sayıda belge olduğu için kabul edilebilir.This is acceptable because there are so few documents in the demo data source. Daha büyük bir veri kaynağı için değeri, 0’dan daha büyük bir değere ayarlarsınız.For a larger data source, you would set the value to greater than 0.

"dataToExtract":"contentAndMetadata" ifade, dizin oluşturucunun, her dosyayla ilgili meta verilerin yanı sıra farklı dosya biçimlerinden içeriği otomatik olarak ayıklamasını söyler.The "dataToExtract":"contentAndMetadata" statement tells the indexer to automatically extract the content from different file formats as well as metadata related to each file.

İçerik ayıklandığında, veri kaynağında bulunan görüntülerden metni ayıklamak için imageAction değerini ayarlayabilirsiniz.When content is extracted, you can set imageAction to extract text from images found in the data source. "imageAction":"generateNormalizedImages" yapılandırması, OCR becerisi ve metin birleştirme beceriyle birlikte kullanıldığında, dizin oluşturucunun görüntülerden metin ayıklamasını söyler (örneğin, bir trafiğin "Durdur" sözcüğünün oturum açmasını durdurur) ve içerik alanının bir parçası olarak katıştırmasını söyler.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. Bu davranış hem belgelerde gömülü olan görüntüler (örneğin, bir PDF’teki görüntü) hem de veri kaynağında bulunan görüntüler (örneğin, bir JPG dosyası) için geçerlidir.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-dizin oluşturmayı izleme4 - Monitor indexing

Dizin oluşturma ve zenginleştirme, oluşturma Dizin Oluşturucu isteğini gönderdikten hemen sonra.Indexing and enrichment commence as soon as you submit the Create Indexer request. Tanımladığınız bilişsel becerilere bağlı olarak, dizin oluşturma biraz zaman alabilir.Depending on which cognitive skills you defined, indexing can take a while. Dizin oluşturucunun halen çalışıp çalışmadığını öğrenmek için aşağıdaki isteği göndererek dizin oluşturucu durumunu denetleyin.To find out whether the indexer is still running, send the following request to check the indexer status.

  1. Dizin oluşturucuyu adlandırmak için, Get ve aşağıdaki URL 'yi kullanın ve hizmet adını hizmetinizin gerçek adıyla değiştirin.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. Dizin oluşturucunun çalışıp çalışmadığını öğrenmek veya hata ve uyarı bilgilerini görüntülemek için yanıtı gözden geçirin.Review the response to learn whether the indexer is running, or to view error and warning information.

Ücretsiz katmanı kullanıyorsanız, şu ileti bekleniyor: ' "belgenizden içerik veya meta veri ayıklanamadı.If you are using the Free tier, the following message is expected: `"Could not extract content or metadata from your document. Ayıklanan metin ' 32768 ' karakter "olarak kesildi.Truncated extracted text to '32768' characters". Bu ileti, boş katmandaki blob dizinlemesi,karakter ayıklamaya karşı bir 32K sınırınasahip olduğundan görüntülenir.This message appears because blob indexing on the Free tier has a32K limit on character extraction. Bu ileti, daha yüksek katmanlarda bu veri kümesi için görmezsiniz.You won't see this message for this data set on higher tiers.

Not

Uyarılar bazı senaryolarda ortaktır ve her zaman bir sorun göstermez.Warnings are common in some scenarios and do not always indicate a problem. Örneğin, bir blob kapsayıcısı görüntü dosyaları içeriyorsa ve işlem hattı görüntüleri işetmez, görüntülerin işlenmediğini belirten bir uyarı alırsınız.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.

Artık yeni alanlar ve bilgiler oluşturduğunuza göre, tipik bir arama senaryosuyla ilişkili olduğu için bilişsel arama değerini anlamak üzere bazı sorgular çalıştıralım.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.

Tüm belgenin tek bir content alanına paketlendiği blob içeriğiyle başladığımızda geri çekin.Recall that we started with blob content, where the entire document is packaged into a single content field. Bu alanda arama yapabilir ve sorgularınızdaki eşleşmeleri bulabilirsiniz.You can search this field and find matches to your queries.

  1. Bir terim veya tümceciğin örneklerini aramak, content alanını ve eşleşen belgelerin sayısını döndürmek için, Get ve aşağıdaki URL 'yi kullanın ve hizmet adını hizmetinizin gerçek adıyla değiştirin.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
    

    Bu sorgunun sonuçları, bir blob Dizin oluşturucuyu bilişsel arama işlem hattı olmadan kullandıysanız alacağınız aynı sonucu veren belge içeriğini döndürür.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. Bu alan aranabilir, ancak modelleri, filtreleri veya otomatik tamamlamayı kullanmak istiyorsanız, kullanılamaz.This field is searchable, but unworkable if you want to use facets, filters, or autocomplete.

    İçerik alanı çıkışıContent field output

  2. İkinci sorgu için, işlem hattı (kişiler, kuruluşlar, konumlar, languageCode) tarafından oluşturulan yeni alanlardan bazılarını döndürün.For the second query, return some of the new fields created by the pipeline (persons, organizations, locations, languageCode). Kısaltma için keyPhrases yok eteceğiz, ancak bu değerleri görmek istiyorsanız dahil etmelisiniz.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
    

    $Select deyimindeki alanlar bilişsel hizmetler 'in doğal dil işleme özellikleri ' nden oluşturulan yeni bilgiler içerir.The fields in the $select statement contain new information created from the natural language processing capabilities of Cognitive Services. Tahmin edebileceğiniz gibi, sonuçlar ve belgelerde çeşitlerdeki bazı gürültü vardır, ancak birçok örnekte analitik modeller doğru sonuçlar üretir.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.

    Aşağıdaki görüntüde, Microsoft 'ta CEO rolü varsayıldığında Satya Nadella 'nın açık harfinin sonuçları gösterilmektedir.The following image shows results for Satya Nadella's open letter upon assuming the CEO role at Microsoft.

    Ardışık düzen çıkışıPipeline output

  3. Bu alanlardan nasıl yararlanabileceği hakkında daha fazla bilgi için, konuma göre eşleşen belge toplamayı döndürmek üzere bir model parametresi ekleyin.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
    

    Bu örnekte, her konum için 2 veya 3 eşleşme vardır.In this example, for each location, there are 2 or 3 matches.

    Model çıkışıFacet output

  4. Bu son örnekte, organizasyonlar koleksiyonuna bir filtre uygulayın ve NASDAQ tabanlı filtre ölçütlerine yönelik iki eşleşme döndürerek.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
    

Bu sorgular, bilişsel arama tarafından oluşturulan yeni alanlara sorgu söz dizimi ve filtreler ile çalışmanın birkaç yolunu gösterir. Daha fazla sorgu örneği için bkz. arama belgeleri REST API, basit sözdizimi sorgu örneklerive tam Lucene sorgu örnekleri.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.

Sıfırlama ve yeniden çalıştırmaReset and rerun

İşlem hattı geliştirmenin erken deneysel aşamalarında, tasarım yinelemeleri için en pratik yaklaşım, nesneleri Azure Bilişsel Arama silmek ve kodunuzun bunları yeniden oluşturması için izin verir.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. Kaynak adları benzersizdir.Resource names are unique. Bir nesneyi sildiğinizde, aynı adı kullanarak nesneyi yeniden oluşturabilirsiniz.Deleting an object lets you recreate it using the same name.

Yeni tanımlarla belgelerinizin yeniden dizinini oluşturmak için:To reindex your documents with the new definitions:

  1. Dizin oluşturucuyu, dizini ve beceri silin.Delete the indexer, index, and skillset.
  2. Nesneleri Değiştir.Modify objects.
  3. İşlem hattını çalıştırmak için hizmetinize yeniden oluşturun.Recreate on your service to run the pipeline.

Dizinleri, Dizin oluşturucuyu ve becerileri silmek için portalı kullanabilir ya da Sil ' i kullanabilir ve her bir nesnenin URL 'sini sağlayabilirsiniz.You can use the portal to delete indexes, indexers, and skillsets, or use DELETE and provide URLs to each object. Aşağıdaki komut bir dizin oluşturucuyu siler.The following command deletes an indexer.

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

Silme işlemi başarılı olduğunda durum kodu 204 döndürülür.Status code 204 is returned on successful deletion.

Kodunuz geliştikçe bir yeniden derleme stratejisini iyileştirmek isteyebilirsiniz.As your code matures, you might want to refine a rebuild strategy. Daha fazla bilgi için bkz. Yeniden dizin derleme.For more information, see How to rebuild an index.

PaketlerTakeaways

Bu öğreticide, veri kaynağı, beceri kümesi, dizin ve dizin oluşturucu gibi bileşen parçalarının oluşturulması yoluyla zenginleştirilmiş bir dizin oluşturma işlem hattı oluşturmaya yönelik temel adımlar gösterilmektedir.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.

Yerleşik yetenekler , Beceri tanımıyla birlikte tanıtılmıştır ve giriş ve çıkışlarla becerilerin zincirlerinin bir araya getirilmiştir.Built-in skills were introduced, along with skillset definition and the mechanics of chaining skills together through inputs and outputs. Ayrıca, işlem hattı tanımındaki outputFieldMappings, işlem hattından bir Azure Bilişsel Arama hizmetinde aranabilir dizine yönlendirme için gerekli olduğunu öğrendiniz.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.

Son olarak, daha fazla yineleme için sonuçların nasıl test edileceğini ve sistemin nasıl sıfırlanacağını öğrendiniz.Finally, you learned how to test results and reset the system for further iterations. Dizine karşı sorgular düzenlendiğinde, zenginleştirilmiş dizin oluşturma işlem hattı tarafından oluşturulan çıktının döndürüldüğünü öğrendiniz.You learned that issuing queries against the index returns the output created by the enriched indexing pipeline.

Kaynakları temizlemeClean up resources

Öğreticiden sonra temizlemenin en hızlı yolu, Azure Bilişsel Arama hizmetini ve Azure Blob hizmetini içeren kaynak grubunu silmelidir.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. Her iki hizmeti de aynı gruba koyduğunuz varsayılarak, şimdi bu öğreticide oluşturduğunuz depolanan içerikler ve hizmetler de dahil olmak üzere, kaynak grubunun içindeki her şeyi silmek için kaynak grubunu silin.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. Portalda kaynak grubu adı, her bir hizmetin Genel Bakış sayfasındadır.In the portal, the resource group name is on the Overview page of each service.

Sonraki adımlarNext steps

Özel becerilerle işlem hattını özelleştirin veya genişletin.Customize or extend the pipeline with custom skills. Özel bir beceri oluşturup bir beceri kümesine eklemeniz, kendi yazdığınız metin veya görüntü analizini eklemenize olanak sağlar.Creating a custom skill and adding it to a skillset allows you to onboard text or image analysis that you write yourself.