# SharePoint

## Co robi

Dzięki integracji SharePoint Speedwave czyta i edytuje pliki, strony oraz listy w jednej witrynie SharePoint, korzystając z Microsoft Graph. Witrynę wskazujesz w chwili podłączenia i Speedwave pozostaje w niej przez cały czas, gdy integracja jest aktywna: prześle dokument, opublikuje stronę czy doda kolumnę do listy, ale nie sięgnie do żadnej innej witryny w twoim tenancie.

## Co potrafi Speedwave

Speedwave dostaje tu 28 narzędzi do plików, stron, list i tożsamości. Żadne z nich nie pyta o witrynę: każde wywołanie sięga po `site_id` wpisany na stałe w workerze. Operacji niszczących nie da się cofnąć.

| Narzędzie | Działanie |
| --- | --- |
| `listFileIds` | Wypisuje pliki i foldery pod wskazaną ścieżką (domyślnie od katalogu głównego witryny). |
| `getFileFull` | Czyta komplet metadanych pliku, a samą zawartość dociąga na żądanie. |
| `downloadFile` | Pobiera plik z SharePoint do lokalnej ścieżki w `/workspace`. |
| `uploadFile` | Wysyła lokalny plik pod wskazaną ścieżkę w SharePoint; do rozstrzygania konfliktów przyjmuje `expectedEtag`, `createOnly` lub `overwrite`. |
| `listPages` | Wypisuje strony witryny. |
| `getPage` | Czyta układ i zawartość strony. |
| `createPage` | Tworzy nową stronę. |
| `updatePage` | Podmienia cały układ strony (Graph nie umie aktualizacji częściowej). |
| `addWebPart` | Dodaje do strony jeden z 13 standardowych typów web part. |
| `updateWebPart` | Zmienia dane istniejącego web part. |
| `removeWebPart` | Usuwa web part ze strony. |
| `publishPage` | Publikuje szkic strony, żeby stał się widoczny. |
| `addImageWebPart` | Dodaje web part z obrazem, który wcześniej wgrałeś do witryny. |
| `generateTableOfContents` | Przegląda nagłówki strony i składa z nich listę z odnośnikami. |
| `listLists` | Wypisuje listy witryny. |
| `getList` | Czyta definicję listy. |
| `createList` | Tworzy nową listę. Wymaga `Sites.Manage.All`. |
| `updateList` | Zmienia nazwę lub ustawienia listy. |
| `deleteList` | Usuwa listę. Operacja nieodwracalna. |
| `addListColumn` | Dodaje do listy kolumnę o określonym typie. Wymaga `Sites.Manage.All`. |
| `removeListColumn` | Usuwa kolumnę z listy. Operacja nieodwracalna. |
| `listItems` | Wypisuje elementy listy, opcjonalnie z filtrem OData `$filter`. |
| `getItem` | Czyta pojedynczy element. |
| `createItem` | Tworzy nowy element. |
| `updateItem` | Zmienia istniejący element. |
| `deleteItem` | Usuwa element. Operacja nieodwracalna. |
| `deletePage` | Usuwa stronę. Operacja nieodwracalna. |
| `getCurrentUser` | Zwraca identyfikator, nazwę wyświetlaną, adres e-mail i user principal name zalogowanego konta. |

Lokalne ścieżki dla `downloadFile` i `uploadFile` muszą mieścić się w `/workspace`, a lista wykluczeń blokuje w tym katalogu dostęp do `.git`, `.env`, `.speedwave`, `.ssh`, `.npmrc`, `.docker` i `.kube`.

## Z czego się składa

Worker SharePoint pracuje we własnym kontenerze i ma pod `/tokens/` dwa pliki podpięte tylko do odczytu: token dostępu oraz identyfikator witryny, do której jest przypisany. Dłużej ważnymi poświadczeniami, czyli client ID, tenant ID i refresh tokenem, zarządza worker OAuth po stronie hosta, trzymając je w pliku powiązanym z projektem, którego kontener nigdy nie podpina. Kiedy któregoś z podpiętych plików brakuje albo jest pusty, worker rusza bez klienta i integracja po prostu zostaje nieaktywna, zamiast krzyczeć błędem.

- ~/.speedwave/oauth/<project>/
  - sharepoint.json stan OAuth widoczny tylko dla hosta: clientId, tenantId, refreshToken
- /tokens/ podpięte do workera tylko do odczytu
  - access_token
  - site_id

## Jak to działa

Logujesz się tylko raz, w schemacie OAuth device-code flow. Autoryzujesz aplikację w przeglądarce, a Speedwave zapisuje otrzymane tokeny na hoście. Dalej to worker OAuth po stronie hosta dostarcza workerowi SharePoint świeży token dostępu, więc kontener nigdy nie widzi refresh tokena. Token odświeża się z wyprzedzeniem, gdy zbliża się jego wygaśnięcie, a także doraźnie, kiedy Graph odpowie `401`. Przy każdym wywołaniu narzędzia w grę wchodzi własny `site_id` workera, odczytany z `/tokens/site_id`.

```mermaid
flowchart LR
  A[Worker SharePoint] -->|potrzebuje świeżego tokena| B[Worker OAuth po stronie hosta]
  B -->|refresh_token| C[Microsoft /oauth2/v2.0/token]
  C -->|nowy access_token| D["/tokens/access_token"]
  D -->|ponowny odczyt| A
```

## Skonfiguruj

Żeby podłączyć SharePoint, potrzebujesz zarejestrowanej aplikacji w Azure AD. Zacznij od ogólnego przebiegu integracji opisanego w [podłącz integrację](/pl/docs/guides/connect-an-integration/), a potem wróć tutaj po trzy wartości typowe dla SharePoint: `client_id`, `tenant_id` i `site_id`.

`site_id` musi być identyfikatorem witryny z Microsoft Graph, a nie adresem URL z przeglądarki, więc posłuż się jedną z dwóch poniższych postaci.

```text title="site_id"
acme.sharepoint.com:/sites/Marketing:
```

Zwróć uwagę na dwukropki: na początku i na końcu.

```text title="site_id"
{hostname},{site-guid},{web-guid}
```

1. Otwórz Ustawienia i odszukaj kartę integracji SharePoint.
2. Wpisz `client_id`, `tenant_id` i `site_id`.
3. Rozpocznij połączenie. Speedwave uruchamia device-code flow i wyświetla kod urządzenia oraz adres URL Microsoftu.
4. Wejdź pod ten adres, podaj kod i zaloguj się kontem, które ma dostęp do witryny. Zatwierdź wskazane uprawnienia.
5. Po zakończeniu logowania Speedwave zapisuje tokeny na hoście i worker SharePoint staje się aktywny.

<DesktopFrame screen="integrations" />
**Zgoda administratora:** Integracja prosi o uprawnienia `Sites.Manage.All`, `Files.ReadWrite.All`, `User.Read` i `offline_access`. `Sites.Manage.All` jest potrzebne do tworzenia list i zwykle wymaga zgody administratora tenanta w Azure AD. Bez tego uprawnienia utworzenie listy się nie uda.

## Granice bezpieczeństwa

Speedwave działa tylko przez Microsoft Graph i tylko na witrynie, do której worker został przypisany przy konfiguracji. Nawigacji witryny nie ruszy, bo Microsoft Graph nie wystawia do niej żadnych endpointów, więc zmiany w nawigacji robisz w interfejsie SharePoint. Kontener nigdy nie trzyma refresh tokena, ma jedynie krótko żyjący token dostępu, którego samodzielnie nie odnowi. To, gdzie leżą te pliki i dlaczego każdy worker widzi wyłącznie poświadczenia swojej własnej usługi, wyjaśniamy w [jak obsługiwane są dane uwierzytelniające](/pl/docs/security/credentials/).