Indeksowanie list kontroli dostępu do dokumentów (ACL) przy użyciu wypychanych interfejsów API REST (wersja zapoznawcza)

Pozyskiwanie uprawnień na poziomie dokumentu za pośrednictwem wypychanych interfejsów API REST (wersja zapoznawcza) umożliwia indeksowanie dokumentów wraz ze skojarzonymi listami kontroli dostępu (ACL) i rolami kontroli dostępu opartej na rolach (RBAC) kontenera. Gdy przesyłasz zawartość do indeksu Wyszukiwanie AI platformy Azure za pośrednictwem interfejsów API REST typu push, usługa zachowuje te uprawnienia dla zaindeksowanej zawartości i wymusza je podczas wykonywania zapytań.

Najważniejsze funkcje obejmują:

• Elastyczna kontrola nad potokami pozyskiwania.
• Ustandaryzowany schemat metadanych uprawnień.
• Obsługa uprawnień hierarchicznych, takich jak listy ACL na poziomie folderu.

W tym artykule wyjaśniamy, jak używać REST API do wypychania w celu indeksowania metadanych uprawnień na poziomie dokumentu w Wyszukiwanie AI platformy Azure. Ten proces przygotowuje indeks do wykonywania zapytań i wymuszania uprawnień użytkownika końcowego w wynikach wyszukiwania.

Wymagania wstępne

• Zawartość z metadanymi listy ACL z Microsoft Entra ID lub innego systemu listy ACL w stylu POSIX-owym. W przypadku pól ACL userIds i groupIds użyj identyfikatorów obiektów Microsoft Entra (identyfikatorów GUID), a nie nazw UPN ani adresów e-mail. Stabilne identyfikatory obiektów zapewniają niezawodne dopasowywanie tożsamości w czasie zapytania, nawet jeśli atrybuty katalogu się zmieniają.

• najnowszy interfejs API REST w wersji zapoznawczej lub pakiet Azure SDK w wersji zapoznawczej zapewniający równoważne funkcje.

• Schemat indeksu ze włączonym permissionFilterOption, oraz atrybuty pól permissionFilter, które przechowują uprawnienia dokumentu.

Ograniczenia

• Pole listy ACL z typem userIds filtru uprawnień lub groupIds może przechowywać co najwyżej 1000 wartości.

• Indeks może przechowywać co najwyżej pięć unikatowych wartości między polami typu rbacScope we wszystkich dokumentach. Nie ma limitu liczby dokumentów, które mają tę samą wartość rbacScope.

• Istniejące pole można zaktualizować, aby uwzględnić przypisanie permissionFilter dla wbudowanego filtrowania metadanych ACL lub RBAC. Aby włączyć filtrowanie dla istniejącego indeksu, dodaj nowe pola lub zaktualizuj istniejące pola, aby uwzględnić permissionFilter wartość.

• W indeksie może istnieć tylko jedno pole każdego permissionFilter typu (każde z groupIds, userIdsi rbacScope).

• Każde permissionFilter pole powinno mieć ustawioną filterable na true.

• Wymuszanie uprawnień w czasie wykonywania zapytania odzwierciedla wartości ACL ostatnio zapisane do indeksu. Jeśli uprawnienia w źródle ulegną zmianie, zmiany te nie będą widoczne, dopóki nie ponownie zaimportujesz lub nie zaktualizujesz dokumentów, których to dotyczy. Zaplanuj przyrostowe ponowne pobieranie lub częściowe aktualizacje, aby utrzymać aktualność list ACL.

• Ta funkcja nie jest obecnie obsługiwana w portalu Azure.

Tworzenie indeksu z polami filtru uprawnień

Indeksowanie list ACL dokumentów i metadanych RBAC przy użyciu interfejsu API REST wymaga skonfigurowania schematu indeksu, który umożliwia filtrowanie uprawnień i zawiera pola z przypisaniami filtrów uprawnień.

Najpierw dodaj element permissionFilterOption. Prawidłowe wartości to enabled lub disabled, a należy ustawić ją na enabled. Możesz przełączyć to na wartość disabled jeśli chcesz wyłączyć funkcję filtrowania uprawnień na poziomie indeksu.

Następnie utwórz pola ciągu dla metadanych uprawnień i uwzględnij element permissionFilter. Pamiętaj, że możesz mieć jeden z każdego typu filtru uprawnień.

Oto podstawowy przykładowy schemat zawierający wszystkie permissionFilter typy:

{  
  "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"
}

W przypadku repozytoriów przedsiębiorstwa, takich jak SharePoint Online, przed wywołaniem interfejsu API push należy na etapie pozyskiwania odwzorować uprawnienia na poziomie dokumentu lub folderu na identyfikatory obiektów użytkowników i grup w usłudze Microsoft Entra. Następnie należy przechowywać te identyfikatory w odpowiednich polach uprawnień.

Przykład indeksowania interfejsu API REST

Po utworzeniu indeksu z polami filtru uprawnień możesz wypełnić te wartości przy użyciu API do indeksowania push, podobnie jak inne pola dokumentu. Oto przykład użycia określonego schematu indeksu, w którym każdy dokument określa akcję indeksowania, pole klucza (DocumentId) i pola uprawnień. Dokumenty powinny również zawierać zawartość, ale to pole zostało pominięte w tym przykładzie w celu zwięzłości.

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"
    }
  ]
}

Reguły ustalania dostępu listy kontroli dostępu (ACL)

W tej sekcji wyjaśniono, jak system określa dostęp do dokumentu użytkownika na podstawie pól uprawnień w każdym dokumencie. Te pola są albo listami ACL (userIds i groupIds, gdzie groupIds obejmuje grupy zabezpieczeń i grupy Microsoft 365), albo zakresem RBAC (rbacScope). Azure ocenia zakres RBAC i listy ACL w zdefiniowanej kolejności, zgodnie z modelem uprawnień usługi ADLS Gen2.

Użytkownik uzyskuje dostęp, spełniając jedno z poniższych kryteriów: pasujący wpis userIds lub groupIds albo odpowiednie przypisanie roli platformy Azure dla rbacScope. Informacje o tym, jak tożsamości wywołujących są udostępniane w czasie wykonywania kwerendy, można znaleźć w sekcji Wymuszanie mechanizmów ACL i RBAC w czasie wykonywania kwerendy.

Specjalne wartości ACL "all" i "none"

Pola listy ACL, takie jak userIds i groupIds, zwykle zawierają listy identyfikatorów GUID (globalnie unikatowych identyfikatorów), które identyfikują użytkowników i grupy z dostępem do dokumentu. Dla tych typów pól listy ACL są obsługiwane dwie specjalne wartości ciągów: "all" i "none". Te wartości działają jako szerokie filtry w celu kontrolowania dostępu na poziomie globalnym, jak pokazano w poniższej tabeli.

Ponieważ użytkownik musi odpowiadać tylko jednemu typowi pola, wartość specjalna "wszystkie" przyznaje dostęp publiczny niezależnie od innych wartości pól listy ACL. Natomiast ustawienie userIds na "none" lub na pustą tablicę oznacza, że użytkownikom nie przyznano dostępu do dokumentu na podstawie identyfikatora użytkownika. Mogą one nadal mieć dostęp dzięki odpowiadającemu identyfikatorowi grupy lub metadanym RBAC.

Przykład kontroli dostępu

Ten przykład ilustruje, jak reguły dostępu do dokumentów są określane na podstawie wartości pól uprawnień w userIds, groupIds i rbacScope. Dla czytelności w tym scenariuszu użyto aliasów, takich jak „user1” i „group1”, zamiast identyfikatorów GUID; w środowisku produkcyjnym używaj identyfikatorów obiektów Microsoft Entra (GUID).

Treści powiązane

• Łączenie się z Wyszukiwanie AI platformy Azure przy użyciu ról
• Egzekwowanie listy ACL i kontroli dostępu opartej na rolach w czasie wyszukiwania
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API