Azure Bilişsel Arama hizmeti için API anahtarları oluşturma ve yönetmeCreate and manage api-keys for an Azure Cognitive Search service

Bir arama hizmetine yapılan tüm istekler için özel olarak hizmetiniz için üretilmiş bir salt okunurdur api anahtarı gerekir.All requests to a search service need a read-only api-key that was generated specifically for your service. API anahtarı, arama hizmeti uç noktanıza erişimin kimliğini doğrulamak için tek mekanizmadır ve her isteğe eklenmelidir.The api-key is the sole mechanism for authenticating access to your search service endpoint and must be included on every request. Rest çözümlerinde, API anahtarı genellikle bir istek üst bilgisinde belirtilir.In REST solutions, the api-key is typically specified in a request header. .Net çözümlerinde, bir anahtar genellikle yapılandırma ayarı olarak belirtilir ve SearchServiceClientüzerinde kimlik bilgileri (yönetici anahtarı) veya searchcredentials (sorgu anahtarı) olarak geçirilir.In .NET solutions, a key is often specified as a configuration setting and then passed as Credentials (admin key) or SearchCredentials (query key) on SearchServiceClient.

Anahtarlar, hizmet sağlama sırasında arama hizmetinize oluşturulur.Keys are created with your search service during service provisioning. Azure Portalanahtar değerlerini görüntüleyebilir ve elde edebilirsiniz.You can view and obtain key values in the Azure portal.

Portal sayfası, ayarları alma, anahtarlar bölümü

API anahtarı nedir?What is an api-key

Bir API anahtarı rastgele oluşturulan rakamlardan ve harflerden oluşan bir dizedir.An api-key is a string composed of randomly generated numbers and letters. Rol tabanlı izinleraracılığıyla anahtarları silebilir veya okuyabilir, ancak bir anahtarı Kullanıcı tanımlı parolayla veya arama işlemlerine erişmek için birincil kimlik doğrulama yöntemi olarak Active Directory kullanamazsınız.Through role-based permissions, you can delete or read the keys, but you can't replace a key with a user-defined password or use Active Directory as the primary authentication methodology for accessing search operations.

Arama hizmetinize erişmek için iki tür anahtar kullanılır: yönetici (okuma/yazma) ve sorgu (salt okuma).Two types of keys are used to access your search service: admin (read-write) and query (read-only).

AnahtarKey AçıklamaDescription SınırlarLimits
YöneticiAdmin Hizmeti yönetme, dizinler, Dizin oluşturucular ve veri kaynakları oluşturma ve silme gibi tüm işlemlere tam haklar verir.Grants full rights to all operations, including the ability to manage the service, create and delete indexes, indexers, and data sources.

Portalda birincil ve İkincil anahtarlar olarak adlandırılan iki yönetici anahtarı, hizmet oluşturulduğunda oluşturulur ve isteğe bağlı olarak tek tek yeniden oluşturulabilir.Two admin keys, referred to as primary and secondary keys in the portal, are 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 Dizinlere ve belgelere salt okuma erişimi verir ve genellikle arama istekleri veren istemci uygulamalarına dağıtılır.Grants read-only access to indexes and 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 only accepts 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.

Mevcut anahtarları bulFind existing keys

Portalda veya yönetim REST APIerişim tuşları elde edebilirsiniz.You can obtain access keys in the portal or through the Management REST API. Daha fazla bilgi için bkz. yönetici ve sorgu API-anahtarlarını yönetme.For more information, see Manage admin and query api-keys.

  1. Azure portalında oturum açın.Sign in to the Azure portal.

  2. Aboneliğiniz için arama hizmetlerini listeleyin.List the search services for your subscription.

  3. Hizmeti seçin ve genel bakış sayfasında, Settings > Yönetim ve sorgu anahtarlarını görüntülemek için ayarlaranahtarlar ' a tıklayın.Select the service and on the Overview page, click Settings >Keys to view admin and query keys.

    Portal sayfası, ayarları alma, anahtarlar bölümü

Sorgu anahtarları oluşturCreate query keys

Sorgu anahtarları bir belge koleksiyonunu hedefleyen işlemler için bir dizin içindeki belgelere salt okuma erişimi için kullanılır.Query keys are used for read-only access to documents within an index for operations targeting a documents collection. Arama, filtre ve öneri sorguları, bir sorgu anahtarı alan tüm işlemlerdir.Search, filter, and suggestion queries are all operations that take a query key. Bir dizin tanımı ya da Dizin Oluşturucu durumu gibi sistem verilerini veya nesne tanımlarını döndüren tüm salt okuma işlemleri bir yönetici anahtarı gerektirir.Any read-only operation that returns system data or object definitions, such as an index definition or indexer status, requires an admin key.

İstemci uygulamalarında erişimi ve işlemleri kısıtlamak, hizmetinizdeki arama varlıklarının korunması için gereklidir.Restricting access and operations in client apps is essential to safeguarding the search assets on your service. İstemci uygulamasından kaynaklanan herhangi bir sorgu için yönetici anahtarı yerine her zaman bir sorgu anahtarı kullanın.Always use a query key rather than an admin key for any query originating from a client app.

  1. Azure portalında oturum açın.Sign in to the Azure portal.

  2. Aboneliğiniz için arama hizmetlerini listeleyin.List the search services for your subscription.

  3. Hizmeti seçin ve genel bakış sayfasında Ayarlar > anahtarlar' a tıklayın.Select the service and on the Overview page, click Settings >Keys.

  4. Sorgu anahtarlarını Yönet' e tıklayın.Click Manage query keys.

  5. Hizmetiniz için önceden oluşturulmuş olan sorgu anahtarını kullanın veya en çok 50 yeni sorgu anahtarı oluşturun.Use the query key already generated for your service, or create up to 50 new query keys. Varsayılan sorgu anahtarı adlandırılmamış, ancak yönetilebilirlik için ek sorgu anahtarları adlandırılmış olabilir.The default query key is not named, but additional query keys can be named for manageability.

    Portal sayfası, ayarları alma, anahtarlar bölümü

Not

Sorgu anahtarı kullanımını gösteren bir kod örneği, C# içindeki bir Azure bilişsel arama dizinini sorgulamabölümünde bulunabilir.A code example showing query key usage can be found in Query an Azure Cognitive Search index in C#.

Yönetici anahtarlarını yeniden oluşturRegenerate admin keys

Bir birincil anahtarı, iş sürekliliği için ikincil anahtarı kullanarak döndürebilmeniz için her bir hizmet için iki yönetici anahtarı oluşturulur.Two admin keys are created for each service so that you can rotate a primary key, using the secondary key for business continuity.

  1. Ayarlar > anahtarlar sayfasında, ikincil anahtarı kopyalayın.In the Settings >Keys page, copy the secondary key.
  2. Tüm uygulamalar için, API anahtarı ayarlarını ikincil anahtarı kullanacak şekilde güncelleştirin.For all applications, update the api-key settings to use the secondary key.
  3. Birincil anahtarı yeniden oluşturun.Regenerate the primary key.
  4. Tüm uygulamaları yeni birincil anahtarı kullanacak şekilde güncelleştirin.Update all applications to use the new primary key.

Her iki anahtarı da aynı anda yeniden oluşturmanız durumunda, bu anahtarları kullanan tüm istemci istekleri HTTP 403 yasaklanmış ile başarısız olur.If you inadvertently regenerate both keys at the same time, all client requests using those keys will fail with HTTP 403 Forbidden. Ancak içerik silinmez ve kalıcı olarak kilitlenmemiştir.However, content is not deleted and you are not locked out permanently.

Hizmete portal veya Yönetim Katmanı (REST API, PowerShellveya Azure Resource Manager) üzerinden erişmeye devam edebilirsiniz.You can still access the service through the portal or the management layer (REST API, PowerShell, or Azure Resource Manager). Yönetim işlevleri, hizmet API anahtarı olmayan bir abonelik KIMLIĞIYLE çalışır ve bu nedenle API anahtarlarınız olmasa bile yine de kullanılabilir.Management functions are operative through a subscription ID not a service api-key, and thus still available even if your api-keys are not.

Portal veya yönetim katmanı aracılığıyla yeni anahtarlar oluşturduktan sonra, yeni anahtarlar ve istekler üzerinde bu anahtarlar sağladığınızda, erişim içeriğinize (dizinler, Dizin oluşturucular, veri kaynakları, eş anlamlı haritalar) geri yüklenir.After you create new keys via portal or management layer, access is restored to your content (indexes, indexers, data sources, synonym maps) once you have the new keys and provide those keys on requests.

Güvenli API anahtarlarıSecure api-keys

Ana güvenlik, portal veya Kaynak Yöneticisi arabirimleri (PowerShell veya komut satırı arabirimi) aracılığıyla erişimi kısıtlayarak bir şekilde yapılır.Key security is ensured by restricting access via the portal or Resource Manager interfaces (PowerShell or command-line interface). Belirtildiği gibi, abonelik yöneticileri tüm API anahtarlarını görüntüleyebilir ve yeniden oluşturabilir.As noted, subscription administrators can view and regenerate all api-keys. Bir önlem olarak, yönetici anahtarlarına kimlerin erişebileceğini anlamak için rol atamalarını gözden geçirin.As a precaution, review role assignments to understand who has access to the admin keys.

  • Hizmet panosunda, hizmetinize ilişkin rol atamalarını görüntülemek için erişim denetimi (IAM) ve ardından rol atamaları sekmesini tıklatın.In the service dashboard, click Access control (IAM) and then the Role assignments tab to view role assignments for your service.

Aşağıdaki rollerin üyeleri anahtarları görüntüleyebilir ve yeniden oluşturabilir: sahip, katkıda bulunan, Arama hizmeti katkıda bulunanlarMembers of the following roles can view and regenerate keys: Owner, Contributor, Search Service Contributors

Not

Arama sonuçları üzerinden kimlik tabanlı erişim için, sonuçları kimliğe göre kırpmak, istek sahibinin erişimi olmaması gereken belgeleri kaldırmak için güvenlik filtreleri oluşturabilirsiniz.For identity-based access over search results, you can create security filters to trim results by identity, removing documents for which the requestor should not have access. Daha fazla bilgi için bkz. Güvenlik filtreleri ve Active Directory Ile güvenli hale getirme.For more information, see Security filters and Secure with Active Directory.

Ayrıca bkz.See also