|
| 1 | +--- |
| 2 | +title: 'Sharepoint Data Connector' |
| 3 | +sidebar_label: 'Sharepoint Data Connector' |
| 4 | +description: 'Sharepoint Data Connector Documentation' |
| 5 | +pagination_prev: null |
| 6 | +--- |
| 7 | + |
| 8 | +The Sharepoint Data Connector enables federated SQL queries on documents stored in Sharepoint. |
| 9 | + |
| 10 | +```yaml |
| 11 | +datasets: |
| 12 | + - from: sharepoint:drive:Documents/path:/top_secrets/ |
| 13 | + name: important_documents |
| 14 | + params: |
| 15 | + sharepoint_client_id: ${secrets:SPICE_SHAREPOINT_CLIENT_ID} |
| 16 | + sharepoint_tenant_id: ${secrets:SPICE_SHAREPOINT_TENANT_ID} |
| 17 | + sharepoint_client_secret: ${secrets:SPICE_SHAREPOINT_CLIENT_SECRET} |
| 18 | +``` |
| 19 | +#### Example |
| 20 | +```sql |
| 21 | +SELECT * FROM important_documents limit 1 |
| 22 | +``` |
| 23 | +Returns |
| 24 | +```json |
| 25 | + |
| 26 | +[ |
| 27 | + { |
| 28 | + "created_by_id": "cbccd193-f9f1-4603-b01d-ff6f3e6f2108", |
| 29 | + "created_by_name": "Jack Eadie", |
| 30 | + "created_at": "2024-09-09T04:57:00", |
| 31 | + "c_tag": "\"c:{BD4D130F-2C95-4E59-9F93-85BD0A9E1B19},1\"", |
| 32 | + "e_tag": "\"{BD4D130F-2C95-4E59-9F93-85BD0A9E1B19},1\"", |
| 33 | + "id": "01YRH3MPAPCNG33FJMLFHJ7E4FXUFJ4GYZ", |
| 34 | + "last_modified_by_id": "cbccd193-f9f1-4603-b01d-ff6f3e6f2108", |
| 35 | + "last_modified_by_name": "Jack Eadie", |
| 36 | + "last_modified_at": "2024-09-09T04:57:00", |
| 37 | + "name": "ngx_google_perftools_module.md", |
| 38 | + "size": 959, |
| 39 | + "web_url": "https://spiceai.sharepoint.com/Shared%20Documents/md/ngx_google_perftools_module.md", |
| 40 | + "content": "# Module ngx_google_perftools_module\n\nThe `ngx_google_perftools_module` module (0.6.29) enables profiling of nginx worker processes using [Google Performance Tools](https://github.com/gperftools/gperftools). The module is intended for nginx developers.\n\nThis module is not built by default, it should be enabled with the `--with-google_perftools_module` configuration parameter.\n\n> **Note:** This module requires the [gperftools](https://github.com/gperftools/gperftools) library.\n\n## Example Configuration\n\n```nginx\ngoogle_perftools_profiles /path/to/profile;\n```\n\nProfiles will be stored as `/path/to/profile.<worker_pid>`.\n\n## Directives\n\n### google_perftools_profiles\n\n- **Syntax:** `google_perftools_profiles file;`\n- **Default:** —\n- **Context:** `main`\n\nSets a file name that keeps profiling information of nginx worker process. The ID of the worker process is always a part of the file name and is appended to the end of the file name, after a dot.\n" |
| 41 | + } |
| 42 | +] |
| 43 | +``` |
| 44 | + |
| 45 | + |
| 46 | +:::warning[Limitations] |
| 47 | +The sharepoint connector does not yet support creating a dataset from a single file (e.g. an Excel spreadsheet). Datasets must be created from a folder of documents (see [Document Support](/components/data-connectors/index.md#document-support)). |
| 48 | +::: |
| 49 | + |
| 50 | + |
| 51 | +## Configuration |
| 52 | +### Parameters |
| 53 | + |
| 54 | +- `sharepoint_client_id`: Required. The client ID of the Azure AD (Entra) application. |
| 55 | +- `sharepoint_tenant_id`: Required. The tenant ID of the Azure AD (Entra) application. |
| 56 | +- `sharepoint_client_secret`: Optional. For service principal authentication. The client secret of the Azure AD (Entra) application. |
| 57 | +- `sharepoint_auth_code`: Optional. For user authentication. The authorization code obtained from the OAuth2 flow (see `spice login sharepoint` [docs](/cli/reference/login)). |
| 58 | + |
| 59 | +Note: Only one of `sharepoint_client_secret` or `sharepoint_auth_code` is allowed. |
| 60 | + |
| 61 | +### `from` formats |
| 62 | + |
| 63 | +The `from` field in a Sharepoint dataset takes the following format: |
| 64 | +```yaml |
| 65 | +from: 'sharepoint:<drive_type>:<drive_id>/<subpath_type>:<subpath_value>' |
| 66 | +``` |
| 67 | +
|
| 68 | +#### Drives |
| 69 | +
|
| 70 | +The sharepoint connector supports datasets from a variety of sources: |
| 71 | + - Drives: A user's OneDrive or a document library in SharePoint. |
| 72 | + - From the drive's name: `from: sharepoint:drive:Documents/...` |
| 73 | + - From the drive's ID: `from: sharepoint:driveId:b!Mh8opUGD80ec7zGXgX9r/...` |
| 74 | + - Sites: A SharePoint site's default document library. |
| 75 | + - From the site's name: `from: sharepoint:site:MySite/...` |
| 76 | + - From the site's ID: `from: sharepoint:siteId:b!Mh8opUGD80ec7zGXgX9r/...` |
| 77 | + - User Drives: A user's OneDrive, `from: sharepoint:me/...`. In this case, no `drive_id` is specified. The user is identified based on the provided authentication. |
| 78 | + - Group Drives: A Group's default document library ( a Microsoft Entra, 365 group, or security group). |
| 79 | + - From the group's name: `from: sharepoint:group:MyGroup/...` |
| 80 | + - From the group's ID: `from: sharepoint:groupId:b!Mh8opUGD80ec7zGXgX9r/...` |
| 81 | + |
| 82 | +For a name-based `drive_id`, the connector will attempt to resolve the name to an ID at startup. |
| 83 | + |
| 84 | +#### Subpaths |
| 85 | + |
| 86 | +Within a drive, the sharepoint connector can load documents from: |
| 87 | + - The root folder: `from: sharepoint:me/root`. In this case, no `subpath_value` is specified. |
| 88 | + - A specific path: `from: sharepoint:me/path:/top_secrets` (`path` being the keyword). |
| 89 | + - A specific folder ID: `from: sharepoint:me/id:01QM2NJSNHBISUGQ52P5AJQ3CBNOXDMVNT` |
| 90 | + |
| 91 | +## Authentication |
| 92 | +As outlined in the [connector parameters](#parameters), the Sharepoint connector supports two types of authentication: |
| 93 | + 1. Service principal authentication, by setting the `sharepoint_client_secret` parameters. |
| 94 | + 2. User authentication, by setting the `sharepoint_auth_code` parameter. Generally this is obtained by running `spice login sharepoint` and following the OAuth2 flow. |
| 95 | + |
| 96 | +### Creating an Enterprise Application |
| 97 | +To use the Sharepoint connector with service principal authentication, you will need to create an Azure AD application and grant it the necessary permissions. This will also support OAuth2 authentication for users within the tenant (i.e. `params.sharepoint_auth_code`). |
| 98 | + |
| 99 | +1. Create a new Azure AD application in the [Azure portal](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview). |
| 100 | +2. Under the application's `API permissions`, add the following permissions: `Sites.Read.All`, `Files.Read.All`, `User.Read`, `GroupMember.Read.All` |
| 101 | + - For service principal authentication, Application permissions are required. For user authentication, only delegated permissions are required. |
| 102 | +3. Add `sharepoint_client_id` and `sharepoint_tenant_id` to the connector configuration. |
| 103 | +4. (For service principal authentication): Under the application's `Certificates & secrets`, create a new client secret. Use this in `params.sharepoint_client_secret`. |
| 104 | + |
| 105 | +### Default Spice Application |
| 106 | +For convenience, Spice AI maintains a default Azure AD application that can be used for Sharepoint authentication. This application requires OAuth2 authentication. To use it: |
| 107 | +```yaml |
| 108 | +datasets: |
| 109 | + - from: sharepoint:me/root # Set the drive and subpath as needed. |
| 110 | + name: my_data |
| 111 | + params: |
| 112 | + sharepoint_client_id: f2b3116e-b4c4-464f-80ec-73cd9d9886b4 |
| 113 | + sharepoint_tenant_id: #{env:TENANT_ID} |
| 114 | + sharepoint_auth_code: ${secrets:SPICE_SHAREPOINT_AUTH_CODE} |
| 115 | +``` |
| 116 | + |
| 117 | +And set the `SPICE_SHAREPOINT_AUTH_CODE` secret via: |
| 118 | +```shell |
| 119 | +spice login sharepoint --tenant-id $TENANT_ID --client-id f2b3116e-b4c4-464f-80ec-73cd9d9886b4 |
| 120 | +``` |
0 commit comments