İzin meta verilerini almak ve arama sonuçlarını kullanıcı erişim haklarına göre filtrelemek için SharePoint dizin oluşturucu kullanma (önizleme)

SharePoint izin meta verilerinin alınması (önizleme), erişim denetim listeleri (ACL’ler) gibi izinlerle ilgili meta verilerini, Microsoft 365’teki SharePoint’ten alınan diğer içeriklerle birlikte korumak için bir Azure Yapay Zeka Arama dizin oluşturucusu kullanır. Dizin oluşturucu, izinleri dizine alınan her belgede meta veri olarak depolar. Sorgu zamanında kullanıcılar yalnızca erişim iznine sahip oldukları belgeleri alır.

Önkoşullar

• Azure Yapay Zeka Arama, herhangi bir bölgede Temel veya daha yüksek bir faturalanabilir katmanda kullanılabilir.

• yapılandırılmış izinlere sahip Microsoft 365 sitelerde, kitaplıklarda, klasörlerde ve dosyalarda SharePoint.

• bu makalede açıklanan ACL'ye özgü gereksinimleri uygulayarak SharePoint dizin oluşturucu belgelerinde tüm yapılandırma adımlarını tamamlayın.

• Microsoft Entra uygulama izinlerini ve senaryonuza uygun bir kimlik bilgilerini yapılandırın. Bkz. ACL'ye göre izinler senaryosu. ACL alma işlemi uygulama izinleri gerektirir. Devredilmiş izinler desteklenmez. Uygulama izinleri ile devredilmiş izinler arasındaki seçim için bkz. İzin yapılandırmanızı seçin.

• REST API sürüm 2026-08-01-preview veya eşdeğer bir önizleme SDK paketi.

Sınırlama

• Artımlı ACL güncelleştirmeleri için 2026-05-01-preview REST API veya üzeri gerekir. Önceki önizleme API sürümlerinde sistem, ACL'leri yalnızca her öğenin ilk alımında yakalar. Sonraki izin değişiklikleri için açık yeniden dizinleme gerekir. Geçiş adımları için bkz. Dizinlenmiş içerik ve kaynak içerik arasındaki izinleri eşitleme.

• Üst kapsamdaki izin değişiklikleri, sonraki dizin oluşturucu çalıştırmalarında otomatik olarak algılanmaz. Yenileme seçenekleri için bkz. Dizinlenmiş içerik ve kaynak içerik arasındaki izinleri eşitleme.

• Azure portalı bu özelliği desteklemez.

• Bu önizlemede aşağıdaki özellikler desteklenmez:

  • SharePoint Bilgi Yönetimi ilkeleri kullanıcı erişimi için geçerlidir. Sistem, sorgu sırasında bu ilkeleri değerlendirmez, içeri aktarmaz veya uygulamaz.

  • "Herkes" veya "Kuruluşunuzdaki kişiler" kapsamına sahip paylaşılabilir bağlantılar. Yalnızca "Belirli kişiler" kapsamına sahip bağlantılar desteklenir.

  • 2026-05-01-preview REST API'sinde SharePoint grupları (Sahipler, Üyeler ve Ziyaretçiler grupları gibi) desteklenir. Bkz. SharePoint grupları desteğini yapılandırma. Önceki önizleme API sürümlerinde yalnızca Microsoft Entra gruplarına çözümleyen SharePoint grupları desteklenir.

• Aşağıdaki dizin oluşturucu özellikleri, SharePoint kaynaklı dizine alınan belgelerde izin devralmayı desteklemez. Bu özelliklerden herhangi birini beceri kümesinde veya dizin oluşturucuda kullanırsanız, belge düzeyi izinleri dizine alınan içeriğe dahil değildir.

  • Özel Web API'si becerisi

  • Bilgi deposu; ajan tabanlı almada görüntü sunumu (önizleme) için gereken varlık deposu da buna dahildir. Bu nedenle görüntü sunma, SharePoint ACL'leri alan bilgi kaynakları için desteklenmez.

  • Dizin oluşturucu zenginleştirme önbelleği

  • Oturumlarda hata ayıklama

SharePoint izin modeli desteği

Bu önizleme belgeler, liste öğeleri ve modern ASPX site sayfaları için temel ACL'leri destekler.

Desteklenen grup ilişkileri

Microsoft Entra grup geçişliliği, Microsoft Entra içinde geçerlidir. SharePoint grupların üyesi olan Microsoft Entra grupları genişletmez.

Hiyerarşik izinler nasıl değerlendirilir?

SharePoint izinleri, devralma bozulmadığı sürece Site → Kitaplığı → Klasör → Dosyası hiyerarşisini devralır.

Alma sırasında, dizin oluşturucu her düzeyde kullanıcı ve grup tanımlayıcılarını (ID) toplar ve her dosya için etkili ACL'yi hesaplar.

ACL’ye göre izin senaryosu

ACL alımı için gereken Microsoft Entra uygulama izinleri ve kimlik bilgisi türü, dizine eklediğiniz öğe türlerine ve grup türlerine bağlıdır. Uygulama kaydında, tüm izinler API izinleri>İzin ekle'nin altına eklenir ve federasyon kimlik bilgileri Sertifikalar ve gizli diziler>Federasyon kimlik bilgileri altına eklenir. Adım adım yönergeler ve ekran görüntüleri için bkz. 3. Adım: Microsoft Entra uygulama kaydı oluşturma ve Kayıtlı uygulamayı yönetilen kimlikle yapılandırma.

Federe kimlik bilgisi, istemci parolası yerine güvenilen bir yönetilen kimlik kullanarak uygulamanın kimliğini doğrulamak için kullanılır. Aynı federasyon kimlik bilgisi hem alma (dizin oluşturucu) hem de SharePoint site gruplarının sorgu zamanı değerlendirmesini kapsar. Kurulum adımları için bkz . Kayıtlı uygulamayı yönetilen kimlikle yapılandırma.

ACL alma işlemini etkinleştirmeden önce

Kayıtlı Microsoft Entra uygulamanızda şu adımları tamamlayın:

1. Dizine neyi eklemeyi planladığınıza (belge kitaplığı dosyaları, liste öğeleri, ASPX site sayfaları) ve SharePoint site gruplarının göz önünde bulundurulması gerekip gerekmediğine göre önceki tablodaki senaryonuzu belirleyin.
2. Microsoft Entra yönetim merkezi uygulama kaydınızı açın ve API izinleri> İzin ekle gidin.
3. Senaryonuz için listelenen Microsoft Graph izinlerini ekleyin. Yönetici onayı verin.
4. Senaryonuz SharePoint izinleri de gerektiriyorsa, İsne izin ekle yeniden seçin, SharePoint API'sini seçin ve Sites.FullControl.All (veya Sites.Selected) ekleyin. Yönetici onayı verin.
5. Kimlik bilgilerini yapılandırın:
   • Yalnızca Microsoft Graph senaryoları için, istemci parolası'nı (Certificates & secrets>Client secrets) veya federasyon kimlik bilgisini kullanabilirsiniz.
   • SharePoint izinleri içeren herhangi bir senaryo için Certificates & secretsFederated credentials altına federasyon kimlik bilgileri ekleyin. Bkz . Kayıtlı uygulamayı yönetilen kimlikle yapılandırma.
6. Dizine eklemek istediğiniz içeriği ve izinleri okuyabilmesi için uygulamaya hedef SharePoint sitelerine erişim izni verin (özellikle kapsamlı erişim için Sites.Selected kullandığınızda önemlidir).

Doğru Microsoft Entra tanımlayıcılarını bulma

Her tanımlayıcı Azure portalında farklı bir konumda görünür ve belirli bir yapılandırma alanıyla eşler. SharePoint ACL alımını federasyon kimlik bilgileriyle yapılandırırken başvuru olarak bu bölümü kullanın. Bu tanımlayıcılara SharePoint grup desteğini yapılandırma bölümünde ve veri kaynağı bağlantı dizesinde atıfta bulunulur.

Federatif kimlik bilgisi uygulama kimliği

FederatedCredentialApplicationId için veri kaynağı bağlantı dizesinde ve dizin tanımındaki federatedCredentialId için, veri alımı uygulamasının kimliğini değil, yönetilen kimliğin kendi uygulama (istemci) kimliğini kullanın.

Sistem tarafından atanan yönetilen kimlik:

1. Azure Yapay Zeka Arama hizmetinize gidin.
2. Güvenlik + ağ>Kimlik öğesini seçin.
3. Sistem tarafından atanan sekmesinde Nesne (sorumlu) kimliğini not edin.
4. Microsoft Entra ID>Enterprise uygulamalarınıyönet'e> gidin.
5. Arama hizmetinizin adını arayın veya Nesne (sorumlu) kimliğini arama kutusuna yapıştırın.
6. Sonucu seçin ve Özellikler'i açın. Burada gösterilen federatedCredentialId kopyalayın; bu, veri kaynağında FederatedCredentialApplicationId ve dizinde değeridir.

Kullanıcı tarafından atanan yönetilen kimlik:

1. Kullanıcı tarafından atanan yönetilen kimlik kaynağına gidin.
2. Ayarlar>Özellikleri'ni seçin.
3. Veri kaynağında FederatedCredentialApplicationId ve dizinde için değer olan federatedCredentialId'ni kopyalayın.

Arama hizmetinizi ACL alımı ve sorgu zamanı zorlaması için yapılandırma

Bu adımlar arama hizmetinizi ACL alımı için yapılandırarak sorgu zamanında ACL'yi kabul etme özelliğini etkinleştirir.

ACL alanlarının doldurulacağı yeri seçme

ACL meta veri alanlarını eşlemeniz, dizin oluşturucunun kaynak öğe başına bir belge mi yoksa kaynak öğe başına birden çok öbek mi yazdığına bağlıdır.

Tüm parçalı senaryolarda, her parça ACL alanlarını taşımalıdır. İzin filtreleri belge başına uygulanır, bu nedenle eksik ACL alanları doğru arayana döndürülemez.

1. Veri kaynağı yapılandırması

Bu bölüm, temel Adım 4: Veri kaynağı oluşturma kılavuzunun en üstünde yer alan bir deltadır. Veri kaynağı tanımında indexerPermissionOptions'yi ayarlayın, böylece SharePoint belgelerinden ve userIds'i dizine ekleyebilirsiniz.

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. Dizin tanımına izin alanları ekleme

ACL'leri depolamak ve sorgu zamanı filtrelemesini desteklemek için dizin şeması tanımınıza alanlar ekleyin.

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

Değerleri doğrulamak için retrievable özniteliğini yalnızca geliştirme sırasında true olarak ayarlayın. Dizin yeniden oluşturma gereksinimi olmadan "retrievable" değerini true'dan false'a değiştirebilirsiniz.

3. Beceri kümenizde dizin projeksiyonlarını yapılandırma (varsa)

Öbekleme etkinleştirildiğinde, projectionModeskipIndexingParentDocuments olduğunda ana belge dizine yazılmaz. ACL meta verilerini indexProjections.selectors[].mappings aracılığıyla her öbeğe taşıyın.

Dizin oluşturucunuz tümleşik vektörleştirmeyi etkinleştirirken Metin Bölme becerisi gibi veri öbekleme özelliğine sahip bir beceri kümesi kullanıyorsa, dizin projeksiyonlarını kullanarak ACL özelliklerini her öbekle eşlediğinizden emin olun. // Aşağıdaki örnekteki satırlar açıklayıcı ek açıklamalardır ve geçerli JSON değildir. İsteği göndermeden önce bunları kaldırın.

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-08-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" } // include when the index has sharePointConnectorAppRegistration (SharePoint groups support)
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

UserIds, GroupIds ve SharePointSiteUrl eşlemeleri, SharePoint dizin oluşturucu (/document/metadata_*) tarafından çıkarılan kaynak düzeyi meta verilerini okur ve değerleri her parçaya yazar.

4. ACL'ler için dizin oluşturucu alan eşlemelerini yapılandırma

Dizin oluşturucu kaynak öğe başına bir belge yazdığında (öbekleme olmadığında) veya öbek dizininin yanında ayrı bir üst dizin tutarken dizin oluşturucu alan eşlemelerini kullanın. Beceri kümeniz, belgeleri projectionMode: skipIndexingParentDocuments kullanarak tek bir hedef dizine öbeklere ayırıyorsa, burada gösterilen alan eşlemelerinin yerini öbek dizini için önceki adımdaki indexProjections.mappings alır.

Gerekli indexer yapılandırmanızın yanı sıra ham meta veri ACL alanlarını SharePoint dizin alanlarınızla eşleyin.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",  "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" }
  ]
}

5. Dizin oluşturucuyu çalıştırın

Dizin oluşturucu çalıştırıldığında ACL meta verileri alır. Dizin oluşturucuyu oluşturduktan veya güncelleştirdikten sonra (bkz . 6. Adım: Dizin oluşturucu oluşturma), dizin oluşturucunun içerikle birlikte ACL'leri de alabilmesi için bir çalıştırma tetikleyin.

POST https://[service name].search.windows.net/indexers/[indexer-name]/run?api-version=2026-08-01-preview
api-key: [admin key]

Öğeleri zaten dizine eklemiş mevcut bir dizin oluşturucuda ACL alımını etkinleştirdiyseniz, bu öğeler için ACL'leri geriye dönük olarak doldurmak üzere /resync öğesini options: ["permissions"] ile çağırın veya belirli öğeleri yeniden ayıklamak için /resetdocs kullanın.

6. ACL alımını doğrulama

ACL değerlerinin doğru doldurulmuş olduğunu onaylamak için:

1. Dizin tanımınızda retrievable ve true üzerinde UserIds değerini geçici olarak GroupIds olarak ayarlayın. retrievable öğesini değiştirmek, dizinin yeniden oluşturulmasını gerektirmez.
2. yükseltilmiş okuma sorgusu çalıştırın; bu sorgu UserIds ve GroupIds öğelerini seçsin ve koleksiyonların boş olmadığını doğrulayın. Öbeklenmiş senaryolar için her öbekte her iki alanın da olduğunu onaylayın.
3. Doğrulamadan sonra retrievable konumuna false geri dönün.

SharePoint grupları desteğini yapılandırma

2026-05-01-preview REST API'sinde başlayarak, SharePoint dizin oluşturucu SharePoint site grubu üyeliklerini (Sahipler, Üyeler, Ziyaretçiler ve özel site grupları) alabilir. Sorgu sırasında bu grupları dikkate alır. SharePoint grup kimlikleri, Microsoft Entra grup nesnesi kimliklerinden ayırt etmek için metadata_group_ids alanında spg: ön ekiyle gösterilir.

Bu kılavuz bağımsızdır: dizini ve dizin oluşturucu alan eşlemelerini yapılandırmak ve SharePoint site grubu zorlaması uygulanarak dizini sorgulamak için adımları sırasıyla tamamlayın.

Aşağıdaki bileşenler birlikte çalışarak SharePoint site grubu çözümlemesini etkinleştirir:

1. Önkoşullar

• SharePoint dizin oluşturucu ACL alımı için zaten yapılandırılmış. ACL’ler için dizin oluşturucunun alan eşlemelerini yapılandırma bölümüne bakın.
• Federe kimlik bilgisi ile Microsoft Entra uygulama kaydı. Bkz . Kayıtlı uygulamayı yönetilen kimlikle yapılandırma.
• REST API 2026-05-01-preview veya daha yeni.

2. Dizini yapılandırma

sharePointConnectorAppRegistration ve SharePointSiteUrl izin filtresi alanlarının yanı sıra UserIds yapılandırmasını ve GroupIds alanını da ekleyin; böylece tam dizin yapısı tek bir yerde olur. tutun permissionFilterOption: "enabled".

PUT https://{service}.search.windows.net/indexes/{index}?api-version=2026-08-01-preview
{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
     "tenantId": "<sharepoint-tenant-id>"
  },
  "fields": [
    { "name": "UserIds",           "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds",          "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "SharePointSiteUrl", "type": "Edm.String", "sharepointSiteUrl": true, "filterable": false, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

3. Dizin oluşturucu alan eşlemelerini yapılandırma

SharePoint meta veri alanlarını tek bir birleşik eşleme bloğundaki dizin alanlarıyla eşleyin. İlk iki eşleme, standart ACL alımı için kullanılan eşlemelerle aynıdır; üçüncü eşleme SharePoint grup çözümlemesini etkinleştirir.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",             "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids",            "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_spo_site_url",  "targetFieldName": "SharePointSiteUrl" }
  ]
}

Beceri kümeniz belgeleri parçalara ayırıyorsa (örneğin, tümleşik vektörleştirme için Metin Bölme becerisiyle), bunun yerine SharePointSiteUrl öğesini indexProjections.mappings aracılığıyla her bir parçaya yansıtın. Bkz. ACL alanlarının doldurulacağı yeri seçme.

4. Dizini sorgulama

İstemci tarafı değişikliği gerekmez. Aynı x-ms-query-source-authorization belirteci hem Microsoft Entra’yı hem de SharePoint site grubu zorunluluğunu etkinleştirir. Arama hizmeti, dizindeki sharePointConnectorAppRegistration kullanarak SharePoint grubu üyelikleri sunucu tarafında çözümler.

İstek yapısı için genel sorgu örneğine ve SharePoint’e özgü SharePoint site grubu zorlaması içeren örneğe bakın.

5. Doğrulama

SharePoint grup kimliklerinin dizine işlendiğini doğrulamak için, öğesini seçen bir GroupIds çalıştırın ve yanıtta spg: ön ekli değerleri arayın.

Dizinlenmiş içerik ve kaynak içerik arasındaki izinleri eşitleme

2026-05-01-preview REST API'sinde başlayarak, her başarılı dizin oluşturucu çalıştırmasında benzersiz izinlere sahip öğeler için ACL değişiklikleri algılanır ve yenilenir. Dizin oluşturucu, rol ataması eklemelerini ve kaldırmalarını artımlı olarak almak için SharePoint değişiklik belirteçlerini kullanır ve aynı şekilde içerik değişikliklerini de alır.

Bazı senaryolar yine de açık bir yenileme gerektirir:

Belirli belgeleri sıfırlama

Belirli belgeleri yeniden içerik ve ACL'leri tamamen almak için sıfırlayabilirsiniz.

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{
  "documentKeys": ["doc123", "doc456"]
}

ACL'leri tüm veri kaynağında yeniden eşitleyin

İlk veri alımından sonra tam veri kümesi ACL içeriğini yeniden eşitleyebilirsiniz. Bu işlemin tam olarak başarılı olması için, tamamlandıktan sonra bir dizin oluşturucu çalıştırılması gerektirir.

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{
  "options": ["permissions"]
}

Verilerinizi ve ACL'lerinizi dizine aldıktan sonra dizini sorgulayabilirsiniz.

Troubleshooting

ACL meta verileri dizine eklendikten sonra, eksik, beklenmeyen veya sorgu sırasında başarısız olan sonuçlar için bkz. SharePoint izin filtreleme sorunlarını giderme.

İlgili içerik

• SharePoint içeriğini Azure Yapay Zeka Arama'te dizinleyin (önizleme)
• Sorgulama anında ACL uygulanması