Edmund AI Dokumentacja
/PRZEWODNIKI KONFIGURACJI

SharePoint — część A: konfiguracja początkowa

Rejestracja aplikacji Entra ID, przyznanie odczytu jednej witryny i wprowadzenie czterech parametrów połączenia.

Konfigurację początkową wykonują jednorazowo administratorzy klienta. Uzyskane cztery wartości wprowadza w Edmundzie osoba z rolą Administrator. Dalsza obsługa jest samodzielna.

Do zgody na uprawnienia w kroku 3 potrzebny jest Global Administrator lub Privileged Role Administrator. Do nadania dostępu do witryny w kroku 4 potrzebny jest SharePoint Administrator.

1. Rejestracja aplikacji w Entra ID

  1. W portalu Entra otwórz Applications → App registrations → New registration.
  2. Wpisz nazwę edmund-sharepoint-readonly. Dla Supported account types wybierz Single tenant. Pozostaw pusty adres przekierowania: aplikacja uwierzytelnia siebie, a nie użytkownika. Kliknij Register.
  3. Ze strony Overview skopiuj przyciskami kopiowania Application (client) ID oraz Directory (tenant) ID. Object ID nie zastępuje żadnej z tych wartości.

2. Utworzenie sekretu klienta

Otwórz Certificates & secrets → New client secret. Ustaw opis i termin wygaśnięcia. Okres 12 miesięcy równoważy częstotliwość rotacji i ryzyko.

Ważne

Natychmiast skopiuj wartość sekretu. Azure pokazuje ją tylko raz. Widoczny obok Secret ID nie jest sekretem i nie pozwala się uwierzytelnić.

Zapisz datę wygaśnięcia. Wygaśnięty sekret zatrzymuje synchronizację: nowe dokumenty przestają docierać, a źródło nie gwarantuje osobnego komunikatu błędu w Edmundzie. Wymianę opisuje część B, rozdział 13.

3. Uprawnienia Microsoft Graph

Otwórz API permissions → Add a permission → Microsoft Graph → Application permissions. Nie wybieraj uprawnień Delegated, ponieważ nie ma zalogowanego użytkownika.

Wybierz jeden wariant:

UprawnienieZakres
Sites.SelectedZalecane. Brak dostępu, dopóki nie zostanie nadany oddzielnie dla witryny
Sites.Read.AllOdczyt wszystkich witryn SharePoint w dzierżawie
Ważne

Files.SelectedOperations.Selected jest innym modelem dostępu do pojedynczych plików udostępnionych aplikacji. Mimo podobnego opisu nie jest obsługiwane przez ten konektor.

Kliknij Grant admin consent. Bez zgody aplikacja nie ma dostępu niezależnie od wpisu na liście. Potwierdzeniem jest stan Granted for <organisation> przy Sites.Selected.

4. Dostęp do jednej witryny

Ten krok dotyczy wyłącznie Sites.Selected. Przy Sites.Read.All zgoda administratora obejmuje wszystkie witryny.

Nadanie dostępu obejmuje całą zawartość danej witryny. Oddzielna witryna dla Edmunda ogranicza zakres w porównaniu z witryną główną dzierżawy, która może zawierać również bibliotekę intranetu.

Samo Sites.Selected niczego nie udostępnia. Muszą być spełnione trzy warunki: zgoda na uprawnienie, nadanie dostępu do witryny oraz odpowiedni zakres w tokenie.

Poniższe wywołania wykonuje administrator dzierżawy w Graph Explorer. Sam Graph Explorer musi mieć zgodę na własny delegowany dostęp Sites.Read.All i Sites.FullControl.All.

Odczyt identyfikatora witryny

GET https://graph.microsoft.com/v1.0/sites/{hostname}:/sites/{site-name}

Pole id w odpowiedzi zawiera nazwę hosta i dwa GUID rozdzielone przecinkami. W następnym wywołaniu użyj całej wartości.

Nadanie odczytu

POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
Content-Type: application/json

{
  "roles": ["read"],
  "grantedToIdentities": [{
    "application": {
      "id": "{application-client-id}",
      "displayName": "edmund-sharepoint-readonly"
    }
  }]
}

Odpowiedź 201 Created potwierdza nadanie dostępu. Zwrócona nazwa aplikacji pozwala sprawdzić, czy wskazano właściwy identyfikator.

Późniejsze odebranie dostępu

GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
DELETE https://graph.microsoft.com/v1.0/sites/{site-id}/permissions/{permission-id}

204 No Content potwierdza usunięcie. Usunięcie tego uprawnienia odbiera dostęp do jednej witryny. Wycofanie zgody w Entra ID odbiera dostęp do wszystkich witryn naraz.

5. Identyfikator biblioteki — Drive ID

Edmund potrzebuje identyfikatora biblioteki przechowującej dokumenty:

GET https://graph.microsoft.com/v1.0/sites/{site-id}/drives

Biblioteka jest widoczna jako Documents; jej id to Drive ID. Jeśli witryna ma kilka bibliotek, wybierz tę z monitorowanymi folderami.

Aplikacja może odczytać identyfikator własnymi danymi uwierzytelniającymi. Jednocześnie sprawdza to sekret i dostęp do witryny:

import msal
import requests

TENANT_ID = "YOUR_TENANT_ID"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SHAREPOINT_HOST = "contoso.sharepoint.com"
SITE_NAME = "sites/edmund-documents"

GRAPH_BASE = "https://graph.microsoft.com/v1.0"


def acquire_token(tenant_id: str, client_id: str, client_secret: str) -> str:
    app = msal.ConfidentialClientApplication(
        client_id,
        authority=f"https://login.microsoftonline.com/{tenant_id}",
        client_credential=client_secret,
    )
    result = app.acquire_token_for_client(
        scopes=["https://graph.microsoft.com/.default"])
    if "access_token" not in result:
        raise RuntimeError(f"Failed to acquire token: {result.get('error_description')}")
    return result["access_token"]


def get_site_id(token: str, host: str, site_name: str) -> str:
    url = f"{GRAPH_BASE}/sites/{host}:/{site_name}"
    resp = requests.get(url, headers={"Authorization": f"Bearer {token}"}, timeout=30)
    resp.raise_for_status()
    return resp.json()["id"]


def get_drive_id(token: str, site_id: str) -> str:
    url = f"{GRAPH_BASE}/sites/{site_id}/drive"
    resp = requests.get(url, headers={"Authorization": f"Bearer {token}"}, timeout=30)
    resp.raise_for_status()
    return resp.json()["id"]


if __name__ == "__main__":
    token = acquire_token(TENANT_ID, CLIENT_ID, CLIENT_SECRET)
    site_id = get_site_id(token, SHAREPOINT_HOST, SITE_NAME)
    print("Site ID: ", site_id)
    print("Drive ID:", get_drive_id(token, site_id))

Skrypt wymaga pakietów msal i requests:

pip install msal requests

Zamiast skryptu można użyć wskazanego wywołania w Graph Explorer.

6. Połączenie w Edmundzie

Administrator otwiera Settings → Connections → SharePoint i wprowadza:

PoleŹródło
Tenant IDDirectory (tenant) ID z kroku 1
Client IDApplication (client) ID z kroku 1
Client secretWartość z kroku 2
Drive IDIdentyfikator z kroku 5

Przed zapisaniem Edmund weryfikuje dane na wskazanej bibliotece. Nieprawidłowe wartości są odrzucane bez zmiany konfiguracji. Zapisane połączenie przeszło więc test dostępu. Sekret nie jest ponownie wyświetlany; widoczna jest tylko informacja, że został zapisany.

Uwaga

Sekret klienta wpisuje bezpośrednio w aplikacji własny administrator. Nie należy wysyłać go zespołowi Edmunda e-mailem ani innym kanałem.

Zapisz termin wygaśnięcia sekretu, aby wymienić go odpowiednio wcześnie zgodnie z częścią B, rozdziałem 13.

Przypisanie folderów do projektów wykonuje się w tym samym miejscu albo na karcie Integrations w ustawieniach projektu. Opisuje je część B, rozdział 11. Nie wymaga to udziału zespołu Edmunda.