Anında iletme REST API'lerini kullanarak belge erişim denetim listelerinin (ACL' ler) dizinini oluşturma (önizleme)

Anında iletme REST API'leri (önizleme) aracılığıyla belge düzeyinde izin alımı, belgeleri ilişkili erişim denetim listeleri (ACL'ler) ve kapsayıcı rolü tabanlı erişim denetimi (RBAC) rolleri ile birlikte dizinlemenizi sağlar. İçeriği push REST API'leri aracılığıyla bir Azure Yapay Zeka Arama dizinine aktardığınızda, hizmet dizine eklenen içerikteki bu izinleri korur ve sorgu sırasında uygular.

Önemli özellikler şunlardır:

• Alım işlem hatları üzerinde esnek denetim.
• İzin meta verileri için standartlaştırılmış şema.
• Klasör düzeyi ACL'ler gibi hiyerarşik izinler için destek.

Bu makalede, Azure Yapay Zeka Arama belge düzeyi izin meta verilerini dizine almak için gönderme REST API'sinin nasıl kullanılacağı açıklanmaktadır. Bu işlem, dizininizi arama sonuçlarında son kullanıcı izinlerini sorgulamaya ve zorlamaya hazırlar.

Önkoşullar

• Microsoft Entra ID veya başka bir POSIX stili ACL sisteminden ACL meta verileri içeren içerik. userIds ve groupIds ACL alanları için, UPN'ler veya e-posta adresleri yerine Microsoft Entra nesne kimliklerini (GUID'ler) kullanın. Kararlı nesne kimlikleri, dizin öznitelikleri değişse bile sorgu zamanında güvenilir kimlik eşleştirmesi sağlar.

• en son önizleme REST API veya eşdeğer özellikler sağlayan bir önizleme Azure SDK paketi.

• Etkin olan permissionFilterOption bir dizin şeması ve permissionFilter belge izinlerini depolayan alan öznitelikleri.

Sınırlama

• İzin filtresi türüne userIds sahip veya groupIds en fazla 1000 değer bulundurabilen bir ACL alanı.

• Dizin, tüm belgelerdeki tür rbacScope alanları arasında en fazla beş benzersiz değer barındırabilir. ile aynı değeri rbacScopepaylaşan belge sayısında bir sınır yoktur.

• Mevcut bir alan, yerleşik ACL veya RBAC meta veri filtreleme ataması içerecek permissionFilter şekilde güncelleştirilebilir. Var olan bir dizinde filtrelemeyi etkinleştirmek için yeni alanlar ekleyin veya mevcut alanları bir değer içerecek şekilde permissionFilter güncelleştirin.

• Dizinde her permissionFilter türden yalnızca bir alan (her biri groupIds, userIds ve rbacScope) bulunabilir.

• Her bir permissionFilter alanının filterable, true olarak ayarlanması gerekir.

• Sorgu zamanı izin zorlaması, dizine son yazılan ACL değerlerini yansıtır. Kaynağa ait izinler değişirse, etkilenen belgeleri yeniden içeri aktarana veya güncelleyene kadar bu değişiklikler yansıtılmaz. ACL'leri güncel tutmak için artımlı yeniden içe aktarma veya kısmi güncelleştirmeler zamanlayın.

• Bu işlev şu anda Azure portalında desteklenmiyor.

İzin filtresi alanlarıyla dizin oluşturma

Belge ACL'lerinin ve RBAC meta verilerinin REST API ile dizine alınması için izin filtrelerini etkinleştiren ve izin filtresi atamalarına sahip alanları olan bir dizin şemasının ayarlanması gerekir.

İlk olarak ekleyin permissionFilterOption. Geçerli değerler enabled veya disabled şeklindedir ve bunu enabled olarak ayarlamanız gerekir. dizin düzeyinde izin filtresi işlevselliğini kapatmak istiyorsanız bunu olarak değiştirebilirsiniz disabled .

İkinci olarak, izin meta verileriniz için dize alanları oluşturun ve ekleyin permissionFilter. Her izin filtresi türünden birine sahip olabileceğinizi unutmayın.

Aşağıda tüm permissionFilter türleri içeren temel bir örnek şema verilmişti:

{  
  "fields": [  
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true },  
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true },  
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true },  
    { "name": "DocumentId", "type": "Edm.String", "key": true }  
  ],
  "permissionFilterOption": "enabled"
}

SharePoint Online gibi kurumsal depolar için, push API’sini çağırmadan önce içeri alma sırasında belge veya klasör düzeyindeki izinleri Microsoft Entra kullanıcı ve grup nesne kimliklerine çözümleyin. Ardından bu kimlikleri ilgili izin alanlarında depolamanız gerekir.

REST API dizin oluşturma örneği

İzin filtresi alanlarına sahip bir dizininiz olduğunda, diğer belge alanlarında olduğu gibi bu değerleri anında iletme dizin oluşturma API'sini kullanarak doldurabilirsiniz. Aşağıda, belirtilen dizin şemasını kullanan ve her belgenin dizin oluşturma eylemini, anahtar alanını (DocumentId) ve izin alanlarını belirttiği bir örnek verilmiştir. Belgeler içerik de içermelidir, ancak bu alanda kısa kullanım için bu örnekte atlanmıştır.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["all"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

ACL erişim çözümleme kuralları

Bu bölümde, sistemin her belgedeki izin alanlarına göre kullanıcının belge erişimini nasıl belirlediğini açıklar. Bu alanlar ya ACL'lerdir (userIds ve groupIds, burada groupIds güvenlik gruplarını ve Microsoft 365 Gruplarını içerir) ya da bir RBAC kapsamıdır (rbacScope). Azure, ADLS 2. Nesil izin modeliyle tutarlı olarak RBAC kapsamını ve ACL'leri tanımlı bir sırada değerlendirir.

Bir kullanıcı, aşağıdaki alanlardan birini sağlayarak erişim elde eder: eşleşen bir userIds veya groupIds girdisi ya da rbacScope için uygun bir Azure rol ataması. Çağıran kimliklerinin sorgu sırasında nasıl sağlandığı hakkında bilgi için bkz. Sorgu sırasında ACL ve RBAC uygulaması.

"Tümü" ve "hiçbiri" özel ACL değerleri

ve userIdsgibi groupIds ACL alanları genellikle belgeye erişimi olan kullanıcıları ve grupları tanımlayan GUID'lerin (Genel Olarak Benzersiz Tanımlayıcılar) listesini içerir. Bu ACL alan türleri için "tümü" ve "hiçbiri" olmak üzere iki özel dize değeri desteklenir. Bu değerler, aşağıdaki tabloda gösterildiği gibi genel düzeyde erişimi denetlemek için geniş filtreler işlevi görür.

Bir kullanıcının yalnızca bir alan türüyle eşleşmesi gerektiğinden, "tümü" özel değeri diğer ACL alan değerlerinden bağımsız olarak genel erişim verir. Buna karşılık, userIds ayarının "yok" veya boş bir dizi olarak belirlenmesi, kullanıcı kimliğine göre hiçbir kullanıcıya belgeye erişim izni verilmediği anlamına gelir. Grup kimliği veya RBAC meta verileri eşlenerek erişim izni verilmeye devam edebilir.

Erişim denetimi örneği

Bu örnekte, , userIdsve groupIdsiçindeki izin alanı değerlerine rbacScopegöre belge erişim kurallarının nasıl çözüldüğü gösterilmektedir. Okunabilirlik için bu senaryoda GUID'ler yerine "user1" ve "group1" gibi takma adlar kullanılır; üretimde Microsoft Entra nesne kimliklerini (GUID'leri) kullanın.

İlgili içerik

• Rolleri kullanarak Azure Yapay Zeka Arama'e bağlanın
• Sorgu zamanı ACL ve RBAC uygulaması
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API