REST öğreticisi: Azure Bilişsel Arama yarı yapılandırılmış verileri (JSON blob 'ları) dizin ve aramaREST Tutorial: Index and search semi-structured data (JSON blobs) in Azure Cognitive Search

Azure Bilişsel Arama, yarı yapılandırılmış verilerin nasıl okunacağını bilen bir Dizin Oluşturucu kullanarak Azure Blob depolamada JSON belgelerini ve dizilerini dizinedebilir.Azure Cognitive Search can index JSON documents and arrays in Azure blob storage using an indexer that knows how to read semi-structured data. Yarı yapılandırılmış veriler, veriler içindeki içeriği ayıran etiketleri veya işaretleri içerir.Semi-structured data contains tags or markings which separate content within the data. Tam olarak dizin oluşturulması gereken yapılandırılmamış veriler arasındaki farkı ve bir ilişkisel veritabanı şeması gibi bir veri modeline bağlı olan, tek başına yapılandırılmış verileri alan temelinde dizinlenebilir şekilde ayırır.It splits the difference between unstructured data, which must be fully indexed, and formally structured data that adheres to a data model, such as a relational database schema, that can be indexed on a per-field basis.

Bu öğreticide, aşağıdaki görevleri gerçekleştirmek için Azure BILIŞSEL arama REST API 'lerini ve bir rest istemcisini kullanın:In this tutorial, use the Azure Cognitive Search REST APIs and a REST client to perform the following tasks:

  • Azure Blob kapsayıcısı için Azure Bilişsel Arama veri kaynağı yapılandırmaConfigure an Azure Cognitive Search data source for an Azure blob container
  • Aranabilir içerik içeren bir Azure Bilişsel Arama dizini oluşturmaCreate an Azure Cognitive Search index to contain searchable content
  • Kapsayıcıyı okumak ve Azure Blob depolama alanından aranabilir içeriği ayıklamak için bir dizin oluşturucuyu yapılandırma ve çalıştırmaConfigure and run an indexer to read the container and extract searchable content from Azure blob storage
  • Oluşturduğunuz dizini aramaSearch the index you just created

ÖnkoşullarPrerequisites

Aşağıdaki hizmetler, Araçlar ve veriler bu hızlı başlangıçta kullanılır.The following services, tools, and data are used in this quickstart.

Geçerli aboneliğinizde bir Azure bilişsel arama hizmeti oluşturun veya var olan bir hizmeti bulun .Create an Azure Cognitive Search service or find an existing service under your current subscription. Bu öğretici için ücretsiz bir hizmet kullanabilirsiniz.You can use a free service for this tutorial.

Örnek verileri depolamak için bir Azure depolama hesabı oluşturun .Create an Azure storage account for storing the sample data.

Azure Bilişsel Arama istek göndermek için Postman masaüstü uygulaması .Postman desktop app for sending requests to Azure Cognitive Search.

Clinical-Trials-JSON. zip Bu öğreticide kullanılan verileri içerir.Clinical-trials-json.zip contains the data used in this tutorial. Bu dosyayı kendi klasörüne indirip sıkıştırmasını açın.Download and unzip this file to its own folder. Veriler, bu öğretici için JSON 'a dönüştürüldü, clinicaltrials.gov'tan kaynaklanır.Data originates from clinicaltrials.gov, converted to JSON for this tutorial.

Anahtar ve URL alGet a key and URL

REST çağrıları için her istekte hizmet URL'sinin ve bir erişim anahtarının iletilmesi gerekir.REST calls require the service URL and an access key on every request. Her ikisiyle de bir arama hizmeti oluşturulur. bu nedenle, aboneliğinize Azure Bilişsel Arama eklediyseniz, gerekli bilgileri almak için aşağıdaki adımları izleyin:A search service is created with both, so if you added Azure Cognitive Search to your subscription, follow these steps to get the necessary information:

  1. Azure Portal oturum açınve arama hizmetine genel bakış sayfasında URL 'yi alın.Sign in to the Azure portal, and in your search service Overview page, get the URL. Örnek uç nokta https://mydemo.search.windows.net şeklinde görünebilir.An example endpoint might look like https://mydemo.search.windows.net.

  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.

HTTP uç noktası ve erişim anahtarı alGet an HTTP endpoint and access key

Tüm istekler hizmetinize gönderilen her istekte bir API anahtarı gerektirir.All requests require an api-key on every request sent to your service. İstek başına geçerli bir anahtara sahip olmak, isteği gönderen uygulama ve bunu işleyen hizmet arasında güven oluşturur.Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

Örnek verileri hazırlamaPrepare sample data

  1. Azure Portal oturum açın, Azure depolama hesabınıza gidin, Bloblar' a tıklayın ve ardından + Container' a tıklayın.Sign in to the Azure portal, navigate to your Azure storage account, click Blobs, and then click + Container.

  2. Örnek veri içeren bir blob kapsayıcısı oluşturun .Create a Blob container to contain sample data. Ortak erişim düzeyini geçerli değerlerinden herhangi birine ayarlayabilirsiniz.You can set the Public Access Level to any of its valid values.

  3. Kapsayıcı oluşturulduktan sonra açın ve komut çubuğunda karşıya yükle ' yi seçin.After the container is created, open it and select Upload on the command bar.

    Komut çubuğuna yükleUpload on command bar

  4. Örnek dosyaları içeren klasöre gidin.Navigate to the folder containing the sample files. Tümünü seçip karşıya yükle' ye tıklayın.Select all of them and then click Upload.

    Dosyaları karşıya yüklemeUpload files

Yükleme tamamlandıktan sonra dosyalar veri kapsayıcısında kendi alt klasöründe görünmelidir.After the upload completes, the files should appear in their own subfolder inside the data container.

Postman’i ayarlamaSet 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 öğreticideki her çağrının istek yöntemi gönderi' dır.The request method for every call in this tutorial is POST. Üst bilgi anahtarları "Content-type" ve "api-key"dir.The header keys are "Content-type" and "api-key." Üst bilgi anahtarlarının değerleri sırayla "application/json" ve "yönetici anahtarınız"dır (yönetici anahtarı, arama birincil anahtarınız için yer tutucudur).The values of the header keys are "application/json" and your "admin key" (the admin key is a placeholder for your search primary key) respectively. Gövde, çağrınızın gerçek içeriklerini yerleştirdiğiniz yerdir.The body is where you place the actual contents of your call. Kullandığınız istemciye bağlı olarak, sorgunuzu oluşturma şeklinizde bazı farklılıklar olabilir. Burada temel bilgiler verilmiştir.Depending on the client you're using, there may be some variations on how you construct your query, but those are the basics.

Yarı yapılandırılmış arama

Arama hizmetinize üç API çağrısı yaparak veri kaynağı, dizin ve dizin oluşturucu oluşturmak için Postman kullanıyoruz.We are using Postman to make three API calls to your search service in order to create a data source, an index, and an indexer. Veri kaynağı, depolama hesabınıza ve JSON verilerinize yönelik bir işaretçi içerir.The data source includes a pointer to your storage account and your JSON data. Arama hizmetiniz, veriler yüklenirken bağlantı kurar.Your search service makes the connection when loading the data.

Sorgu dizeleri bir api sürümü belirtmeli ve her çağrının oluşturulan bir 201döndürmesi gerekir.Query strings must specify an api-version and each call should return a 201 Created. JSON dizilerini kullanmak için genel olarak kullanılabilen api-Version 2019-05-06.The generally available api-version for using JSON arrays is 2019-05-06.

REST istemcinizden aşağıdaki üç API çağrısını yürütün.Execute the following three API calls from your REST client.

Veri kaynağı oluşturmaCreate a data source

Veri kaynağı oluşturma API 'si, hangi verilerin dizine oluşturulacağını belirten bir Azure bilişsel arama nesnesi oluşturur.The Create Data Source APIcreates an Azure Cognitive Search object that specifies what data to index.

Bu çağrının uç noktası: https://[service name].search.windows.net/datasources?api-version=2019-05-06.The endpoint of this call is https://[service name].search.windows.net/datasources?api-version=2019-05-06. [service name] değerini, arama hizmetinizin adıyla değiştirin.Replace [service name] with the name of your search service.

Bu çağrı için, istek gövdesi depolama hesabınızın adını, depolama hesabı anahtarınızı ve BLOB kapsayıcısı adını içermelidir.For this call, the request body must include the name of your storage account, storage account key, and blob container name. Depolama hesabı anahtarı, Azure portalında depolama hesabınızın Erişim Anahtarları bölümünde bulunur.The storage account key can be found in the Azure portal inside your storage account's Access Keys. Aşağıdaki resimde konum gösterilmektedir:The location is shown in the following image:

Yarı yapılandırılmış arama

Çağrıyı yürütmeden önce çağrın gövdesinde [storage account name], [storage account key]ve [blob container name] değiştirdiğinizden emin olun.Make sure to replace [storage account name], [storage account key], and [blob container name] in the body of your call before executing the call.

{
    "name" : "clinical-trials-json",
    "type" : "azureblob",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=[storage account name];AccountKey=[storage account key];" },
    "container" : { "name" : "[blob container name]"}
}

Yanıt şöyle görünmelidir:The response should look like:

{
    "@odata.context": "https://exampleurl.search.windows.net/$metadata#datasources/$entity",
    "@odata.etag": "\"0x8D505FBC3856C9E\"",
    "name": "clinical-trials-json",
    "description": null,
    "type": "azureblob",
    "subtype": null,
    "credentials": {
        "connectionString": "DefaultEndpointsProtocol=https;AccountName=[mystorageaccounthere];AccountKey=[[myaccountkeyhere]]];"
    },
    "container": {
        "name": "[mycontainernamehere]",
        "query": null
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null
}

Dizin oluşturunCreate an index

İkinci çağrı, tüm aranabilir verileri depolayan bir Azure Bilişsel Arama dizini oluşturan Dizin API 'Si oluşturur.The second call is Create Index API, creating an Azure Cognitive Search index that stores all searchable data. Dizin, tüm parametreleri ve parametrelerin özniteliklerini belirtir.An index specifies all the parameters and their attributes.

Bu çağrının URL’si: https://[service name].search.windows.net/indexes?api-version=2019-05-06.The URL for this call is https://[service name].search.windows.net/indexes?api-version=2019-05-06. [service name] değerini, arama hizmetinizin adıyla değiştirin.Replace [service name] with the name of your search service.

İlk olarak URL’yi değiştirin.First replace the URL. Daha sonra aşağıdaki kodu kopyalayıp gövdeye yapıştırın ve sorguyu çalıştırın.Then copy and paste the following code into your body and run the query.

{
  "name": "clinical-trials-json-index",  
  "fields": [
  {"name": "FileName", "type": "Edm.String", "searchable": false, "retrievable": true, "facetable": false, "filterable": false, "sortable": true},
  {"name": "Description", "type": "Edm.String", "searchable": true, "retrievable": false, "facetable": false, "filterable": false, "sortable": false},
  {"name": "MinimumAge", "type": "Edm.Int32", "searchable": false, "retrievable": true, "facetable": true, "filterable": true, "sortable": true},
  {"name": "Title", "type": "Edm.String", "searchable": true, "retrievable": true, "facetable": false, "filterable": true, "sortable": true},
  {"name": "URL", "type": "Edm.String", "searchable": false, "retrievable": false, "facetable": false, "filterable": false, "sortable": false},
  {"name": "MyURL", "type": "Edm.String", "searchable": false, "retrievable": true, "facetable": false, "filterable": false, "sortable": false},
  {"name": "Gender", "type": "Edm.String", "searchable": false, "retrievable": true, "facetable": true, "filterable": true, "sortable": false},
  {"name": "MaximumAge", "type": "Edm.Int32", "searchable": false, "retrievable": true, "facetable": true, "filterable": true, "sortable": true},
  {"name": "Summary", "type": "Edm.String", "searchable": true, "retrievable": true, "facetable": false, "filterable": false, "sortable": false},
  {"name": "NCTID", "type": "Edm.String", "key": true, "searchable": true, "retrievable": true, "facetable": false, "filterable": true, "sortable": true},
  {"name": "Phase", "type": "Edm.String", "searchable": false, "retrievable": true, "facetable": true, "filterable": true, "sortable": false},
  {"name": "Date", "type": "Edm.String", "searchable": false, "retrievable": true, "facetable": false, "filterable": false, "sortable": true},
  {"name": "OverallStatus", "type": "Edm.String", "searchable": false, "retrievable": true, "facetable": true, "filterable": true, "sortable": false},
  {"name": "OrgStudyId", "type": "Edm.String", "searchable": true, "retrievable": true, "facetable": false, "filterable": true, "sortable": false},
  {"name": "HealthyVolunteers", "type": "Edm.String", "searchable": false, "retrievable": true, "facetable": true, "filterable": true, "sortable": false},
  {"name": "Keywords", "type": "Collection(Edm.String)", "searchable": true, "retrievable": true, "facetable": true, "filterable": false, "sortable": false},
  {"name": "metadata_storage_last_modified", "type":"Edm.DateTimeOffset", "searchable": false, "retrievable": true, "filterable": true, "sortable": false},
  {"name": "metadata_storage_size", "type":"Edm.String", "searchable": false, "retrievable": true, "filterable": true, "sortable": false},
  {"name": "metadata_content_type", "type":"Edm.String", "searchable": true, "retrievable": true, "filterable": true, "sortable": false}
  ],
  "suggesters": [
  {
    "name": "sg",
    "searchMode": "analyzingInfixMatching",
    "sourceFields": ["Title"]
  }
  ]
}

Yanıt şöyle görünmelidir:The response should look like:

{
    "@odata.context": "https://exampleurl.search.windows.net/$metadata#indexes/$entity",
    "@odata.etag": "\"0x8D505FC00EDD5FA\"",
    "name": "clinical-trials-json-index",
    "fields": [
        {
            "name": "FileName",
            "type": "Edm.String",
            "searchable": false,
            "filterable": false,
            "retrievable": true,
            "sortable": true,
            "facetable": false,
            "key": false,
            "indexAnalyzer": null,
            "searchAnalyzer": null,
            "analyzer": null,
            "synonymMaps": []
        },
        {
            "name": "Description",
            "type": "Edm.String",
            "searchable": true,
            "filterable": false,
            "retrievable": false,
            "sortable": false,
            "facetable": false,
            "key": false,
            "indexAnalyzer": null,
            "searchAnalyzer": null,
            "analyzer": null,
            "synonymMaps": []
        },
        ...
          "scoringProfiles": [],
    "defaultScoringProfile": null,
    "corsOptions": null,
    "suggesters": [],
    "analyzers": [],
    "tokenizers": [],
    "tokenFilters": [],
    "charFilters": []
}

Dizin Oluşturucu oluşturma ve çalıştırmaCreate and run an indexer

Bir dizin oluşturucu veri kaynağını bağlar, verileri hedef arama dizinine aktarır ve isteğe bağlı olarak veri yenilemeyi otomatikleştirmek için bir zamanlama sağlar.An indexer connects the data source, imports data into the target search index, and optionally provides a schedule to automate the data refresh. REST API Dizin Oluşturucu oluşturur.The REST API is Create Indexer.

Bu çağrının URL’si: https://[service name].search.windows.net/indexers?api-version=2019-05-06.The URL for this call is https://[service name].search.windows.net/indexers?api-version=2019-05-06. [service name] değerini, arama hizmetinizin adıyla değiştirin.Replace [service name] with the name of your search service.

İlk olarak URL’yi değiştirin.First replace the URL. Ardından aşağıdaki kodu kopyalayıp gövdeye yapıştırın ve isteği gönderin.Then copy and paste the following code into your body and send the request. İstek hemen işlenir.The request is processed immediately. Yanıt geri geldiğinde, tam metin ile aranabilir bir dizininiz olur.When the response comes back, you will have an index that is full-text searchable.

{
  "name" : "clinical-trials-json-indexer",
  "dataSourceName" : "clinical-trials-json",
  "targetIndexName" : "clinical-trials-json-index",
  "parameters" : { "configuration" : { "parsingMode" : "jsonArray" } }
}

Yanıt şöyle görünmelidir:The response should look like:

{
    "@odata.context": "https://exampleurl.search.windows.net/$metadata#indexers/$entity",
    "@odata.etag": "\"0x8D505FDE143D164\"",
    "name": "clinical-trials-json-indexer",
    "description": null,
    "dataSourceName": "clinical-trials-json",
    "targetIndexName": "clinical-trials-json-index",
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": null,
        "maxFailedItemsPerBatch": null,
        "base64EncodeKeys": null,
        "configuration": {
            "parsingMode": "jsonArray"
        }
    },
    "fieldMappings": [],
    "enrichers": [],
    "disabled": null
}

JSON dosyalarınızı aramaSearch your JSON files

İlk belge yüklendikten hemen sonra aramaya başlayabilirsiniz.You can start searching as soon as the first document is loaded. Bu görev için portalda Arama Gezgini ' ni kullanın.For this task, use Search explorer in the portal.

Azure portal, arama hizmeti genel bakış sayfasını açın, dizinler listesinde oluşturduğunuz dizini bulun.In Azure portal, open the search service Overview page, find the index you created in the Indexes list.

Az önce oluşturduğunuz dizini seçtiğinizden emin olun.Be sure to choose the index you just created.

Yapılandırılmamış arama

Önceden olduğu gibi veriler birçok şekilde sorgulanabilir: tam metin araması, sistem özellikleri veya kullanıcı tanımlı meta veriler.As before, the data can be queried in a number of ways: full text search, system properties, or user-defined metadata. Hem sistem özellikleri hem de kullanıcı tanımlı meta veriler yalnızca hedef dizin oluşturulurken $selectalınabilirolarak işaretlendiyse parametresiyle aranabilir.Both system properties and user-defined metadata may only be searched with the $select parameter if they were marked as retrievable during creation of the target index. Dizindeki parametreler oluşturulduktan sonra değiştirilemez.Parameters in the index may not be altered once they are created. Ancak ek parametreler eklenebilir.However, additional parameters may be added.

Temel bir sorgu örneği $select=Gender,metadata_storage_size olup bu, dönüşü bu iki parametreyle sınırlar.An example of a basic query is $select=Gender,metadata_storage_size, which limits the return to those two parameters.

Yarı yapılandırılmış arama

Daha karmaşık sorgu örneği $filter=MinimumAge ge 30 and MaximumAge lt 75 olup bu, yalnızca MinimumAge parametrelerinin 30 değerinden büyük veya bu değere eşit ve MaximumAge parametresinin 75’ten küçük olduğu sonuçları döndürür.An example of more complex query would be $filter=MinimumAge ge 30 and MaximumAge lt 75, which returns only results where the parameters MinimumAge is greater than or equal to 30 and MaximumAge is less than 75.

Yarı yapılandırılmış arama

Birkaç sorguyu daha denemek istiyorsanız rahatça bunu yapabilirsiniz.If you'd like to experiment and try a few more queries yourself, feel free to do so. Karşılaştırma işleçlerini (eq, ne, gt, lt, ge, le) değil, Mantıksal işleçleri (and, or, not) kullanabileceğinizi unutmayın.Know that you can use Logical operators (and, or, not) and comparison operators (eq, ne, gt, lt, ge, le). Dize karşılaştırmaları büyük/küçük harfe duyarlıdır.String comparisons are case-sensitive.

$filter parametresi yalnızca dizininiz oluşturulurken filtrelenebilir olarak işaretlenmiş olan meta verilerle birlikte çalışır.The $filter parameter only works with metadata that were marked filterable at the creation of your index.

Kaynakları temizlemeClean up resources

Öğreticiden sonra temizlemenin en hızlı yolu, Azure Bilişsel Arama 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. Kaynak grubunu silerek içindeki her şeyi kalıcı olarak silebilirsiniz.You can delete the resource group now to permanently delete everything in it. Portalda, kaynak grubu adı Azure Bilişsel Arama hizmeti 'nin genel bakış sayfaalıdır.In the portal, the resource group name is on the Overview page of Azure Cognitive Search service.

Sonraki adımlarNext steps

JSON bloblarını dizine almanın çeşitli yaklaşımları ve birden çok seçeneği vardır.There are several approaches and multiple options for indexing JSON blobs. Bir sonraki adım olarak, senaryonuza en uygun şeyi görmek için çeşitli seçenekleri gözden geçirin ve test edin.As a next step, review and test the various options to see what works best for your scenario.