Azure Bilişsel Arama hizmet RESTAzure Cognitive Search Service REST

Azure Bilişsel Arama, özel uygulamalara zengin arama deneyimi sağlayan, tam olarak yönetilen bir bulut arama hizmetidir.Azure Cognitive Search is a fully managed cloud search service that provides a rich search experience to custom applications. Arama özelliği eklemenin bir yolu, dizin oluşturup yöneten, veri yükleyen, arama özelliklerini uygulayan, sorgular yürüten ve sonuçları işleyen işlemlerle REST API’sidir.One way to add search capability is through a REST API, with operations that create and manage indexes, load data, implement search features, execute queries, and handle results.

Hizmet yönetimi için hizmet sağlama veya kapasiteyi değiştirme dahil ayrı bir REST API sağlanır.A separate REST API is provided for service administration, including provisioning the service or altering capacity. Daha fazla bilgi için bkz. Azure bilişsel arama yönetimi geri kalanı.For more information, see Azure Cognitive Search Management REST.

Hizmeti oluşturmak için bkz. Azure bilişsel arama hizmeti oluşturma.To create the service, see Create an Azure Cognitive Search service.

Önemli kavramlarKey concepts

Azure Bilişsel Arama, Arama Hizmetleri ve dizinler ve Belgelerkavramlarını içerir. burada arama hizmeti, aranabilir verilerin kalıcı olarak depolanmasını sağlayan bir veya daha fazla dizin içerir ve veriler JSON belgeleri biçiminde yüklenir.Azure Cognitive Search has the concepts of search services and indexes and documents, where a search service contains one or more indexes that provide persistent storage of searchable data, and data is loaded in the form of JSON documents. Veriler dış veri kaynağından bir dizine itilir, ancak bir Dizin Oluşturucukullanıyorsanız, verileri ayıklamak ve dizine yüklemek için bir veri kaynağını gezinmek mümkündür.Data can be pushed to an index from an external data source, but if you use an indexer, it's possible to crawl a data source to extract and load data into an index.

AI zenginleştirme becerileri işlemleri ekliyor.AI enrichment adds skillsets operations. Becerileri, Dizin oluşturucularda iliştirilir.Skillsets are attached to indexers. Dizin Oluşturucu yürütme, Dizin Oluşturucu başına bir beceri ile bir beceri çağıran eylemdir.Indexer execution is the action that invokes a skillset, with one skillset per indexer.

Hizmette yürütülen beş tür işlem vardır:There are five types of operations that can be executed against the service:

  • Dizin yönetimi işlemleri.Index management operations. Arama dizini oluşturun, silin, güncelleştirin veya yapılandırın.Create, delete, update, or configure a search index.

  • Belge işlemleri.Document operations. Dizinde belge ekleme, güncelleştirme veya silme, dizini sorgulama veya belirli belgeleri KIMLIĞE göre arama.Add, update, or delete documents in the index, query the index, or look up specific documents by ID.

  • Dizin Oluşturucu işlemleri.Indexer operations. Bir veri kaynağını ve isteğe bağlı olarak zamanladığınız veya çalıştırabileceğiniz bir Dizin oluşturucuyu yapılandırarak dizin oluşturma işleminin yönlerini otomatikleştirin.Automate aspects of an indexing operation by configuring a data source and an indexer that you can schedule or run on demand. Bu özellik, Azure üzerinde sınırlı sayıda veri kaynağı türü için desteklenir.This feature is supported for a limited number of data source types on Azure.

  • Beceri işlemleri.Skillset operations. Bir AI zenginleştirme iş yükünün parçası olan bir beceri, bir dizi zenginleştirme işlemini tanımlar.Part of an AI enrichment workload, a skillset defines a series of enrichment processing. Bir beceri, bir Dizin Oluşturucu tarafından kullanılır.A skillset is consumed by an indexer.

  • Eş anlamlı eşleme işlemleri.Synonym map operations. Eş anlamlı eşleme, Kullanıcı tanımlı eş anlamlıları içeren hizmet düzeyi kaynağıdır.A synonym map is service-level resource that contains user-defined synonyms. Bu kaynak arama dizinlerinden bağımsız olarak tutulur.This resource is maintained independently from search indexes. Karşıya yüklendikten sonra, herhangi bir aranabilir alanı, eş anlamlı haritaya (alan başına bir tane) işaret edebilirsiniz.Once uploaded, you can point any searchable field to the synonym map (one per field).

API 'Leri çağırmaCalling the APIs

Bu bölümde belgelenen API 'Ler, dizin oluşturma ve doldurma, belge yükleme ve sorgular gibi arama verileri üzerinde işlemlere erişim sağlar.The APIs documented in this section provide access to operations on search data, such as index creation and population, document upload, and queries. API 'Leri çağırırken aşağıdaki noktaları göz önünde bulundurun:When calling APIs, keep the following points in mind:

  • Tüm API 'Lerin HTTPS üzerinden verilmesi gerekir (varsayılan bağlantı noktası 443 ' de).All APIs must be issued over HTTPS (on the default port 443).

  • Arama hizmetiniz tam nitelikli etki alanı adı (örneğin: mysearchservice.search.windows.net ') ile benzersiz şekilde tanımlanır ` .Your search service is uniquely identified by a fully-qualified domain name (for example: `mysearchservice.search.windows.net`).

  • Tüm API istekleri, sağladığınız arama hizmeti için oluşturulan bir API anahtarı içermelidir.All API requests must include an api-key that was generated for the search service you provisioned. İ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.

  • Tüm API istekleri URI içindeki API sürümünü içermelidir.All API requests must include the api-version in the URI. Değeri, aşağıdaki örnekte gösterildiği gibi geçerli hizmet sürümünün sürümü olarak ayarlanmalıdır:Its value must be set to the version of the current service release, shown in the following example:

    GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • Tüm API istekleri isteğe bağlı olarak Accept HTTP üst bilgisini ayarlayabilir.All API requests can optionally set the Accept HTTP header. Üst bilgi ayarlanmamışsa, varsayılan olarak varsayılır application/json .If the header is not set, the default is assumed to be application/json.

Uç NoktaEndpoint

Hizmet işlemleri için uç nokta, sağladığınız Azure Bilişsel Arama hizmetinin URL 'sidir: https:// <yourService> . Search.Windows.net.The endpoint for service operations is the URL of the Azure Cognitive Search service you provisioned: https://<yourService>.search.windows.net.

Kimlik Doğrulama ve YetkilendirmeAuthentication and Authorization

Arama hizmetinize yönelik her HTTP isteğinin kimliği, iki bilgi parçasına göre doğrulanır: bir arama hizmeti URL 'SI ve kanıt sağlayan bir API anahtarı , isteği güvenilir bir varlıktan.Every HTTP request to your search service is authenticated based on two pieces of information: a search service URL and an api-key that provides proof the request is from a trusted entity. Farklı işlem düzeyleri için iki tür api anahtarı vardır.There are two types of api-keys for different levels of operation.

AnahtarKey AçıklamaDescription SınırlarLimits
YöneticiAdmin Yönetici anahtarları, hizmeti yönetme, durum ve nesne tanımlarını alma, dizinler, Dizin oluşturucularve veri kaynaklarıoluşturma ve silme özelliği dahil tüm işlemlere tam haklar verir.Admin keys grant full rights to all operations, including the ability to manage the service, get status and object definitions, and create and delete indexes, indexers, and data sources.

Portalda birincil ve İkincil anahtarlar olarak anılan iki yönetici API-anahtarıotomatik olarak oluşturulur ve isteğe bağlı olarak tek tek yeniden oluşturulabilir.Two admin api-keys, referred to as primary and secondary keys in the portal, are automatically generated when the service is created and can be individually regenerated on demand. İki anahtara sahip olmak, hizmete devam etmek için ikinci anahtarı kullanırken bir anahtarın üzerine erişmenizi sağlar.Having two keys allows you to roll over one key while using the second key for continued access to the service.

Yönetici anahtarları yalnızca HTTP istek üst bilgilerinde belirtilir.Admin keys are only specified in HTTP request headers. Bir URL 'ye yönetici API anahtarı yerleştirebilirsiniz.You cannot place an admin api-key in a URL.
Hizmet başına en fazla 2Maximum of 2 per service
SorguQuery Sorgu anahtarları bir dizin (belgeler) içindeki içeriğe salt okuma erişimi verir ve genellikle arama istekleri veren istemci uygulamalarına dağıtılır.Query keys grant read-only access to content within an index (documents), and are typically distributed to client applications that issue search requests.

Sorgu anahtarları isteğe bağlı olarak oluşturulur.Query keys are created on demand. Bunları portalda el ile veya yönetim REST APIaracılığıyla oluşturabilirsiniz.You can create them manually in the portal or programmatically via the Management REST API.

Sorgu anahtarları, arama, öneri veya arama işlemi için bir HTTP isteği üst bilgisinde belirtilebilir.Query keys can be specified in an HTTP request header for search, suggestion, or lookup operation. Alternatif olarak, bir URL 'ye parametre olarak bir sorgu anahtarı geçirebilirsiniz.Alternatively, you can pass a query key as a parameter on a URL. İstemci uygulamanızın isteği nasıl formüllamasına bağlı olarak, anahtarı bir sorgu parametresi olarak geçirmek daha kolay olabilir:Depending on how your client application formulates the request, it might be easier to pass the key as a query parameter:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]
hizmet başına 5050 per service

Görsel olarak, bir yönetici anahtarı veya sorgu anahtarı arasında ayrım yoktur.Visually, there is no distinction between an admin key or query key. Her iki anahtar de 32 rasgele oluşturulan alfasayısal karakterlerden oluşan dizelerdir.Both keys are strings composed of 32 randomly-generated alpha-numeric characters. Uygulamanızda hangi anahtar türünün belirtilme izini kaybederseniz, portalda anahtar değerlerini denetleyebilir veya değer ve anahtar türünü döndürmek için REST API kullanabilirsiniz.If you lose track of what type of key is specified in your application, you can check the key values in the portal or use the REST API to return the value and key type.

Not

İstek URI 'sinde bir gibi hassas verileri geçirmek için kötü bir güvenlik uygulaması olduğu kabul edilir api-key .It is considered a poor security practice to pass sensitive data such as an api-key in the request URI. Bu nedenle, Azure Bilişsel Arama sorgu dizesinde yalnızca bir sorgu anahtarını kabul eder api-key ve dizininizin içeriği herkese açık bir şekilde kullanılabilir olmadığı sürece bunu yapmaktan kaçınmalısınız.For this reason, Azure Cognitive Search will only accept a query key as an api-key in the query string, and you should avoid doing so unless the contents of your index should be publicly available. Genel bir kural olarak, api-key isteğinizi istek üst bilgisi olarak geçirmeyi öneririz.As a general rule, we recommend passing your api-key as a request header.

Azure Bilişsel Arama yetkilendirmeAuthorization in Azure Cognitive Search

Yetkilendirme, Azure portal sağlanan rol tabanlı erişim denetimleri (RBAC) aracılığıyla yönetim işlemleri için kullanılabilir.Authorization is available for administrative operations via the role-based access controls (RBAC) provided in the Azure portal. RBAC rolleri, hizmet yönetimine yönelik erişim düzeylerini tüm hizmetler arasında tutarlı bir şekilde ayarlamak için kullanılır.RBAC roles are used to set levels of access for service administration in a way that is consistent across all services. Örneğin, yönetici anahtarı gibi hassas verileri görüntüleme, sahip ve katkıda bulunan rolleriyle kısıtlıdır, ancak hizmet durumunu görüntülemek herhangi bir rolün üyeleri tarafından kullanılabilir.For example, viewing sensitive data, such as the admin key, is restricted to the Owner and Contributor roles, whereas viewing service status is available to members of any role.

Azure Bilişsel Arama, kendi arama merkezli işlemleri için bir yetkilendirme modeli sağlamıyor.For its own search-centric operations, Azure Cognitive Search does not provide an authorization model. Ancak, belge ve Kullanıcı ilişkilendirmeleriyle bir dizin yükleme olanağına sahipseniz, arama sonuçlarını kullanıcı kimliğine göre filtreleyebilirsiniz.However, if you have the ability to load an index with document and user associations, you can filter search results based on user identity. Daha fazla bilgi için bkz. Azure bilişsel arama sonuçları kırpma Için güvenlik filtreleri.For more information, see Security filters for trimming results in Azure Cognitive Search.

Ayrıca bkz.See also