Azure AI Arama REST API başvurusu
Azure AI Arama (eski adıyla Azure Bilişsel Arama), kullanıcıya ait içerik üzerinden 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.
Denetim düzlemi işlemlerine ayrı bir Yönetim REST API'si aracılığıyla erişilir.
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şvuru > Veri Düzlemi klasöründen olduğundan emin olun.
Önemli kavramlar
Azure AI Arama arama hizmetleri, dizinler, belgeler, dizin oluşturucular, veri kaynakları, beceri kümeleri ve eş anlamlı haritalar kavramlarına sahiptir.
- Arama hizmeti dizinleri, dizin oluşturucuları, veri kaynaklarını, beceri kümelerini ve eş anlamlı eşlemleri üst düzey nesneler olarak barındırıyor.
- Arama dizini, arama belgelerinin kalıcı olarak depolanmasını sağlar. Arama belgeler, dış kaynaklardan yüklenen ve aranabilir hale getirmek için bir 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şturucunun, dizin oluşturma işlem hattına yapay zeka zenginleştirme ve tümleşik vektörleştirme ekleyen bir beceri kümesi de olabilir. Beceri kümeleri her zaman bir dizin oluşturucuya eklenir. Bir arama hizmeti tarafından dizine alınabilmesi 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.
Tümüyle, bir arama hizmetinde aşağıdaki nesneleri oluşturabilirsiniz:
| Nesneler | Description |
|---|---|
| Veri kaynakları | Dizin oluşturma belgelerini almak ve yenilemek için dizin oluşturucu tarafından kullanılan veri kaynağı bağlantısı. Veri kaynaklarının bir typevardır. Azure için Microsoft tarafından sağlanan bağlantıları veya iş ortakları aracılığıyla üçüncü taraf bağlayıcıları kullanabilirsiniz. Tam liste için bkz. Veri kaynakları galerisi . |
| Belgeler | Kavramsal olarak, belge dizininizdeki bir varlıktır. Bu kavramı daha tanıdık veritabanı eşdeğerleriyle eşleme: arama dizini bir tabloya eşittir ve belgeler kabaca tablodaki satırlara eşdeğerdir. Belgeler yalnızca bir dizinde bulunur ve yalnızca bir 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çimli belge işlemleri her zaman belirli bir dizin adı için dahil /indexes/[index name]/docs olur. |
| Dizinler | Dizin, arama hizmetinizde depolanır ve bilgi almak için dizine alınmış ve belirteç haline getirilmiş JSON belgeleriyle doldurulur. Bir dizinin fields koleksiyonu, arama belgesinin yapısını tanımlar. Alanların nasıl kullanıldığını 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 ayarlaması için puanlama profilleri, önerenler, anlamsal yapılandırmalar ve özel çözümleyiciler gibi diğer yapıları da tanımlar. |
| Dizin Oluşturucular | 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 bir veri kaynağındaki bağlantı bilgilerini kullanarak bir 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ütmesine dış işlem adımları ekler ve genellikle içeriği analiz etmek veya dönüştürerek dizinde aranabilir hale getirmek için yapay zeka veya derin öğrenme modelleri eklemek için kullanılır. Beceri kümesinin içeriği, Microsoft tarafından oluşturulan yerleşik beceriler, özel beceriler veya her ikisinin birleşimi olabilecek bir veya daha fazla beceridir. OCR ve doğal dil işleme dahil olmak üzere görüntü analizi için yerleşik beceriler vardır. Diğer yerleşik becerilere örnek olarak varlık tanıma, anahtar ifade ayıklama, metni mantıksal sayfalara bölme ve diğerleri verilebilir. Beceri kümesi, dizinlere, dizin oluşturuculara ve veri kaynaklarına eşdeğer bir düzeyde bulunan ü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ş anlamlı eşlemine işaret edebilirsiniz (alan başına bir tane). |
İzinler ve erişim denetimi
Microsoft Entra ID aracılığıyla anahtar tabanlı kimlik doğrulaması veya rol tabanlı kullanabilirsiniz.
Anahtar tabanlı kimlik doğrulaması , arama hizmeti için oluşturulan API anahtarlarına dayanır. İ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. Okuma-yazma işlemleri için bir Yönetici API anahtarı veya arama dizininin belge koleksiyonuna okuma erişimi için sorgu API'si anahtarı kullanabilirsiniz.
kimlik doğrulaması ve rol tabanlı erişim denetimi Microsoft Entra ID, Microsoft Entra ID'de güvenlik sorumluları ve rol atamalarıyla birlikte yerleşik bir kiracınız olmasını gerektirir. Aşağıdaki rollerin üyelerinin veri düzlemi erişimi vardır. Yerleşik roller yetersizse özel roller oluşturabilirsiniz.
Rol Access Arama Hizmet Katkıda Bulunanı Nesnelere erişim, ancak dizin içeriğine erişim yok. Bu rol bir arama dizinini sorgulayamaz, arama dizininde belge ekleyemez, kaldıramaz veya güncelleştiremez. Bu rol, nesneleri yönetmesi gereken ancak nesne verilerini görüntüleme veya bunlara erişme yeteneği olmayan yöneticilere yöneliktir. veri dizini katkıda bulunanı Arama 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. veri dizini okuyucu Arama 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 gösterir. Bunu ayarlama konusunda yardım için bkz. Microsoft Entra ID kullanarak arama uygulamasına erişimi yetkilendirme.
Anahtar tabanlı kimlik doğrulamayı veya rol tabanlı kimlik doğrulamayı devre dışı bırakabilirsiniz. Rol tabanlı kimlik doğrulamayı devre dışı bırakırsanız bazı yerleşik rollerin erişimi devam eder. Ayrıntılar için bkz. Azure AI Arama için kimlik doğrulaması ve rol tabanlı erişim denetimi Microsoft Entra ID.
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ı göz önünde bulundurun:
İsteklerin HTTPS üzerinden verilmesi gerekir (varsayılan bağlantı noktası 443'te).
İstek URI'leri api sürümünü 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=2020-06-30İstek üst bilgileri , kimliği doğrulanmış bağlantılar için api anahtarı veya 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 olarak olduğu varsayılır
application/json.