hot.dev/microsoft-sharepoint / ::microsoft::sharepoint

SharePoint Online over Microsoft Graph: sites, document libraries, lists and list items, and per-site app grants. Credentials, clouds, retries and errors come from microsoft-graph; files in document libraries go through microsoft-onedrive (a library is a drive: pass its id as opts.drive).

Namespaces

• ::microsoft::sharepoint::sites - root site, site by URL or path, search, subsites, libraries
• ::microsoft::sharepoint::lists - lists, list items with field selection, create/update/delete, subscriptions
• ::microsoft::sharepoint::permissions - Sites.Selected / Lists.SelectedOperations.Selected app grants

Site ids look like contoso.sharepoint.com,{site-collection-guid},{web-guid}. Get one from sites/get-site-by-url, sites/search-sites or sites/get-root-site, and keep it.

Quick start

::sites ::microsoft::sharepoint::sites
::items ::microsoft::onedrive::items
::content ::microsoft::onedrive::content

site ::sites/get-site-by-url("https://contoso.sharepoint.com/sites/engineering")
lib ::sites/find-drive(site.id, "Documents")
files ::items/list-all-children("root", {drive: lib.id}, 100)
doc ::content/read-document(first(files), "pdf")

Functions

get-site-by-url alias of ::microsoft::sharepoint::sites/get-site-by-url

fn (url: Str): Map
fn (url: Str, opts: Map): Map

GET a site from its browser URL (https://contoso.sharepoint.com/sites/eng, or a library or page URL inside it). See parse-site-url.

site ::microsoft::sharepoint::sites/get-site-by-url("https://contoso.sharepoint.com/sites/engineering")

grant-site alias of ::microsoft::sharepoint::permissions/grant-site

fn (site-id: Str, app-id: Str, display-name: Str?, roles: Vec): Map
fn (site-id: Str, app-id: Str, display-name: Str?, roles: Vec, opts: Map): Map

POST /sites/{site-id}/permissions - grant app app-id (its client id) roles on a site, for an app consented Sites.Selected. Needs Sites.FullControl.All. Returns the permission (keep its id to revoke).

// Run once with an admin app's credentials
grant ::microsoft::sharepoint::permissions/grant-site(site-id, "11111111-2222-3333-4444-555555555555", "Contoso Indexer", ["read"], {
  client-id: admin-app-id, client-secret: admin-secret, tenant-id: "contoso.onmicrosoft.com"
})
grant.id

list-drives alias of ::microsoft::sharepoint::sites/list-drives

fn (site-id: Str): Vec
fn (site-id: Str, opts: Map): Vec

GET /sites/{site-id}/drives - the site's document libraries, each a drive (id, name, webUrl, driveType: "documentLibrary"). Pass a library's id as opts.drive to microsoft-onedrive.

list-items alias of ::microsoft::sharepoint::lists/list-items

fn (site-id: Str, list: Str): Map
fn (site-id: Str, list: Str, opts: Map): Map

GET /sites/{site}/lists/{list}/items - one page of items with their fields: Graph's {value, @odata.nextLink?}. See items-query.

page ::microsoft::sharepoint::lists/list-items(site-id, "Tickets", {
  fields: ["Title", "Status", "Priority"],
  filter: "fields/Status eq 'Open'",
  allow-non-indexed: true,
  top: 50
})
map(page.value, (i) { i.fields.Title })

list-path

fn (site-id: Str, list: Str): Str

The Graph path of a list by id or display name under a site: /sites/{site}/lists/{list} (pure).

search-sites alias of ::microsoft::sharepoint::sites/search-sites

fn (query: Str): Vec
fn (query: Str, opts: Map): Vec
fn (query: Str, opts: Map, limit: Int?): Vec

GET /sites?search={query} - sites whose name or description matches, all pages or at most limit. "*" lists every site the caller can see.

hits ::microsoft::sharepoint::sites/search-sites("engineering", {}, 20)
map(hits, (s) { s.webUrl })

site-path

fn (site-id: Str): Str

The Graph path of a site by id: /sites/{encoded id} (pure). Site ids contain commas, which are encoded.