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.

• Folder~/.speedwave/oauth/<project>/

  • sharepoint.json stan OAuth widoczny tylko dla hosta: clientId, tenantId, refreshToken
• Folder/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.

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ę, 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.

Postać ścieżkowa

site_id

acme.sharepoint.com:/sites/Marketing:

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

Postać złożona

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.

Service integrations my my-project

servicestatusveron

githubrunningconfigured

gitlabrunningconfigured

slackconfigure →—

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.