Azure AI Search REST API başvurusu

  • Makale

Azure AI Search (eski adıyla Azure Bilişsel Arama), kullanıcıya ait içerik üzerinde bilgi alma sağlayan tam olarak yönetilen bir bulut arama hizmetidir.

Veri düzlemi REST API'leri dizin oluşturma ve sorgu iş akışları için kullanılır ve bu bölümde belgelenmiştir.

Hizmet yönetimi için denetim düzlemi işlemleri ayrı bir Yönetimi REST API'sikapsamındadır.

Sürüme alınan API belgeleri

REST API belgeleri artık sürümlenmiştir. BIR API başvuru sayfasını açtığınızda, içindekiler tablosunun üzerinde bir sürüm seçici görüntülenir. API başvurusunun Başvurusu > Veri Düzlemi klasöründen olduğundan emin olun.

Sürüm seçicinin ekran görüntüsü.

Temel kavramlar

Azure AI Search,arama hizmetleridizinleri,belgeleri, dizin oluşturucuları,veri kaynakları,beceri kümeleri ve eş anlamlı haritalarkavramlarına sahiptir.

  • Arama hizmeti dizinleri, dizin oluşturucuları, veri kaynaklarını, beceri kümelerini ve eş anlamlıları üst düzey nesneler olarak barındırıyor.
  • Arama dizini, arama belgelerinin kalıcı olarak depolanmasını sağlar. Arama belgeleri, dış kaynaklardan yüklenen ve aranabilir hale getirmek için dizine gönderilen bir alan koleksiyonu olarak ifade edilen verilerinizdir.
  • Arama dizin oluşturucu, verileri yerel biçimlerde okuyarak ve JSON olarak seri hale getirerek otomasyon ekler.
  • Dizin oluşturucu bir veri kaynağına sahiptir ve bir dizine işaret etmektedir.
  • Dizin oluşturucu, dizin oluşturma işlem hattına yapay zeka zenginleştirme ekleyen ve tümleşik vektörleştirme bir beceri kümesine de sahip olabilir. Beceri kümeleri her zaman bir dizin oluşturucuya eklenir. Bir arama hizmeti tarafından geliştirilmiş dizin oluşturma için metin ayıklamak veya öbek oluşturmak, içeriği vektörleştirmek, özellikleri çıkarmak veya içeriğe yapı eklemek için makine öğrenmesini çağırır.

Bir arama hizmetinde aşağıdaki nesneleri oluşturabilirsiniz:

Nesne Açıklama
Veri kaynakları Dizin oluşturucu tarafından dizin oluşturma belgelerini almak ve yenilemek için kullanılan veri kaynağı bağlantısı. Veri kaynaklarının typevardır. Azure için Microsoft tarafından sağlanan bağlantıları veya iş ortağı bağlayıcılarını kullanabilirsiniz. Tam liste için bkz. Veri kaynakları galerisi.
Evrak Kavramsal olarak, belge dizininizdeki bir varlıktır. Bu kavramı daha tanıdık veritabanı eşdeğerleriyle eşleme: arama dizini tabloya eşittir ve belgeler kabaca tablodaki satırlarla eşdeğerdir. Belgeler yalnızca bir dizinde bulunur ve yalnızca dizinin belge koleksiyonunu (/docs) hedefleyen sorgular aracılığıyla alınır. Belgeleri karşıya yükleme, birleştirme, silme veya sorgulama gibi koleksiyonda gerçekleştirilen tüm işlemler tek bir dizin bağlamında gerçekleşir, bu nedenle URL biçimindeki belge işlemleri her zaman belirli bir dizin adı için /indexes/[index name]/docs içerir.
Dizin Dizin, arama hizmetinizde depolanır ve bilgi almak için dizine alınmış ve belirteç haline getirilmiş JSON belgeleriyle doldurulur. Bir dizinin alan koleksiyonu, arama belgesinin yapısını tanımlar. Alanların kullanımı belirleyen bir adı, veri türleri ve öznitelikleri vardır. Örneğin, searchable alanları tam metin aramasında kullanılır ve bu nedenle dizin oluşturma sırasında belirteç haline getirilir. Dizin ayrıca ilgi ayarı için puanlama profilleri, önericiler, anlamsal yapılandırmalar ve özel çözümleyiciler gibi diğer yapıları da tanımlar.
Dizinleyicileri Dizin oluşturucular dizin oluşturma otomasyonu sağlar. Dizin oluşturucu bir veri kaynağına bağlanır, verileri okur ve hedef arama dizinine dizin oluşturmak için bir arama altyapısına geçirir. Dizin oluşturucular, veri kaynağındaki bağlantı bilgilerini kullanarak dış kaynaktan okur ve gelen verileri JSON arama belgelerine serileştirir. Bir veri kaynağına ek olarak, dizin oluşturucu da dizin gerektirir. Dizin, arama belgelerinin alanlarını ve özniteliklerini belirtir.
Beceri Kümeleri Beceri kümesi dizin oluşturucu yürütmeye dış işleme adımları ekler ve dizinde daha iyi aranabilirlik için içeriği analiz etmek veya dönüştürmek üzere yapay zeka veya derin öğrenme modelleri uygulamak için kullanılır. Beceri kümesinin içeriği,bir veya daha fazla beceridir. Bu, Microsoft tarafından oluşturulan yerleşik beceriler , özel beceriler veya her ikisinin birleşimi olabilir. OCR ve doğal dil işleme dahil olmak üzere görüntü analizi için yerleşik beceriler mevcuttur. Diğer yerleşik becerilere örnek olarak varlık tanıma, anahtar ifade ayıklama, metinleri mantıksal sayfalara ayırma ve diğerleri verilebilir. Beceri kümesi, dizinlere, dizin oluşturuculara ve veri kaynaklarına eşdeğer bir düzeyde mevcut olan üst düzey tek başına nesnedir, ancak yalnızca dizin oluşturucu işlemesi içinde çalışır. Üst düzey bir nesne olarak, bir beceri kümesini bir kez tasarlayabilir ve sonra birden çok dizin oluşturucuda buna başvurabilirsiniz.
Eş anlamlı haritalar Eş anlamlı eşlem, kullanıcı tanımlı eş anlamlılar içeren hizmet düzeyi nesnesidir. Bu nesne arama dizinlerinden bağımsız olarak korunur. Karşıya yüklendikten sonra, aranabilir herhangi bir alanı eş anlamlı eşlemine işaret edebilirsiniz (alan başına bir tane).

İzinler ve erişim denetimi

Anahtar tabanlı kimlik doğrulamayı veya rol tabanlı kimlik doğrulamayı Microsoft Entra Id aracılığıyla kullanabilirsiniz.

  • Anahtar tabanlı kimlik doğrulaması, arama hizmeti için oluşturulan API anahtarlarını kullanır. Geçerli bir anahtara sahip olmak, isteği gönderen uygulama ile bunu işleyen hizmet arasında istek temelinde güven oluşturur. Okuma-yazma işlemleri için Yönetici API anahtarı veya bir arama dizininin belge koleksiyonuna okuma erişimi için Sorgu API anahtarı kullanabilirsiniz.

  • Microsoft Entra Id kimlik doğrulaması ve rol tabanlı erişim denetimi , Microsoft Entra Id'de güvenlik sorumluları ve rol atamaları ile yerleşik bir kiracınız olmasını gerektirir. Aşağıdaki rollerin üyeleri veri düzlemi erişimine sahiptir. Yerleşik roller yetersizse özel roller oluşturabilirsiniz.

    Rol Erişim
    Arama Hizmeti Katkıda Bulunanı Nesnelere erişim, ancak dizin içeriğine erişim yoktur. Bu rol bir arama dizini ve diğer üst düzey nesneler oluşturur, ancak arama dizinini sorgulayamaz, arama dizininde belge ekleyemez, kaldıramaz veya güncelleştiremez. Bu rol, nesne tanımları oluşturan, güncelleştiren ve silen geliştiricilere yöneliktir. Ayrıca nesneleri yönetmesi gereken ancak nesne verilerini görüntüleme veya bunlara erişme olanağı olmayan yöneticiler için de bu özelliktir.
    Arama Veri Dizini Katkıda Bulunanı Dizin içeriğine okuma-yazma erişimi. Bu rol, bir dizinin belge koleksiyonunu içeri aktarması, yenilemesi veya sorgulaması gereken geliştiricilere veya dizin sahiplerine yöneliktir.
    Arama Veri Dizini Okuyucusu Dizin içeriğine okuma erişimi. Bu rol, sorgu çalıştıran uygulamalar ve kullanıcılar içindir.

Bağlantıda rolleri kullanırken, istemci uygulamanız yetkilendirme üst bilgisinde bir taşıyıcı belirteci sunar. Bu ayarın ayarlanmasıyla ilgili yardım için bkz. Microsoft Entra ID kullanarak arama uygulamasına erişim yetkisi verme.

Anahtar tabanlı kimlik doğrulamayı veya rol tabanlı kimlik doğrulamayı devre dışı bırakabilirsiniz. Rol tabanlı kimlik doğrulamasını devre dışı bırakırsanız, bu yalnızca veri düzlemi işlemleri için geçerlidir. Hizmet yönetimi gibi denetim düzlemi işlemleri her zaman rol tabanlı kimlik doğrulaması kullanır. Ayrıntılar için bkz. Azure AI Search için Microsoft Entra Id kimlik doğrulaması ve rol tabanlı erişim denetimi .

API'leri çağırma

Bu bölümde belgelenen API'ler dizin oluşturma ve popülasyon, belge karşıya yükleme ve sorgular gibi arama verileri üzerindeki işlemlere erişim sağlar. API'leri çağırırken aşağıdaki noktaları aklınızda bulundurun:

  • İstekler HTTPS üzerinden yapılmalıdır (varsayılan bağlantı noktası 443'te).

  • İstek URI'leri api sürümüiçermelidir. Değer desteklenen bir sürüme ayarlanmalıdır ve bu örnekte gösterildiği gibi biçimlendirilmelidir: GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01

  • İstek üst bilgileriapi anahtarı veya kimliği doğrulanmış bağlantılar için taşıyıcı belirteci içermelidir. İsteğe bağlı olarak, HTTP Kabul Et üst bilgisini ayarlayabilirsiniz. İçerik türü üst bilgisi ayarlı değilse, varsayılan değerin application/jsonolduğu varsayılır.

Ayrıca bkz.