SharePoint

The SharePoint connector provides SQL access to SharePoint services and servers.

Supported versions

This connector supports Windows SharePoint Services 3.0, Microsoft Office SharePoint Server 2007 and above, and SharePoint Online.

Before you begin

Before using the SharePoint connector, do the following tasks:

  • In your Google Cloud project:
    • Grant the roles/connectors.admin IAM role to the user configuring the connector.
    • Grant the following IAM roles to the service account that you want to use for the connector:
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      A service account is a special type of Google account intended to represent a non-human user that needs to authenticate and be authorized to access data in Google APIs. If you don't have a service account, you must create a service account. For more information, see Creating a service account.

    • Enable the following services:
      • secretmanager.googleapis.com (Secret Manager API)
      • connectors.googleapis.com (Connectors API)

      To understand how to enable services, see Enabling services.

    If these services or permissions have not been enabled for your project previously, you are prompted to enable them when configuring the connector.

Configure the SharePoint app in Azure (AD)

If you choose to use the Azure Active Directory (AD) for the online edition of SharePoint, follow these steps to configure the SharePoint app in Azure AD:

  1. In the Azure AD portal, select your organization's directory.
  2. In the Manage section, click App registrations and then click New registration.
  3. Register the app in Azure AD by filling the registration details:
    1. For Supported account types, select Accounts in this organizational directory only.
    2. For Redirect URI (optional), select Web and add https://your_connections_host.spo.index.html as the URI for your connections users to receive their authentication response.
    3. Click Register.

      4. For more information, see how to register an application in Azure.

  4. From your app's Overview page, click API permissions and then click Add a permission.
  5. Configure your application to access a web API by following these steps:
    1. For Request API permissions, select SharePoint from the Microsoft APIs tab.
    2. For Delegated Permissions, select Read and write user files and Read and write items in all site collections.
    3. Click Add permissions.
    4. From your configured API permissions screen, select Grant admin consent for your_organizational_directory.
  6. Add a redirect URI for your organization's SharePoint mobile app:
    1. Click Authentication.
    2. In Web, click Add URI and add https://your_connections_host/spo/mobile.html as the reply URL for mobile users.
    3. In Implicit grant, select both Access tokens and ID tokens.
    4. Click Save.
  7. Edit the Azure Active Directory app manifest to allow the open authentication used by the app:
    1. From the app's Overview page, click the Manifest section.
    2. Change the attribute oauth2AllowImplicitFlow to true.
    3. Click Save.
  8. From your app's Overview page, make a note of the Application (client) ID. You need to provide it in the authentication section when you are configuring the SharePoint connector if you choose the Azure AD authentication type.

Configure the connector

Configuring the connector requires you to create a connection to your data source (backend system). A connection is specific to a data source. It means that if you have many data sources, you must create a separate connection for each data source. To create a connection, do the following steps:

  1. In the Cloud console, go to the Integration Connectors > Connections page and then select or create a Google Cloud project.

    Go to the Connections page

  2. Click + Create new to open the Create Connection page.
  3. In the Location section, choose the location for the connection.
    1. Region: Select a location from the drop-down list.

      Supported regions for connectors include:

      For the list of all the supported regions, see Locations.

    2. Click Next.
  4. In the Connection Details section, complete the following:
    1. Connector: Select SharePoint from the drop down list of available Connectors.
    2. Connector version: Select the Connector version from the drop down list of available versions.
    3. In the Connection Name field, enter a name for the Connection instance.

      Connection names must meet the following criteria:

      • Connection names can use letters, numbers, or hyphens.
      • Letters must be lower-case.
      • Connection names must begin with a letter and end with a letter or number.
      • Connection names cannot exceed 63 characters.
    4. Optionally, enter a Description for the connection instance.
    5. Service Account: Select a service account that has the required roles.
    6. Optionally, configure the Connection node settings:

      • Minimum number of nodes: Enter the minimum number of connection nodes.
      • Maximum number of nodes: Enter the maximum number of connection nodes.

      A node is a unit (or replica) of a connection that processes transactions. More nodes are required to process more transactions for a connection and conversely, fewer nodes are required to process fewer transactions. To understand how the nodes affect your connector pricing, see Pricing for connection nodes. If you don't enter any values, by default the minimum nodes are set to 2 (for better availability) and the maximum nodes are set to 50.

    7. Optionally, click + Add label to add a label to the Connection in the form of a key/value pair.
    8. Click Next.
  5. In the Destinations section, enter details of the remote host (backend system) you want to connect to.
    1. Destination Type: Select a Destination Type. For example, host address is https://xxxxx.sharepoint.com.
      1. In the Host address field, specify the hostname or IP address of the destination.
        1. If you want to establish a private connection to your backend systems, follow these steps:
          1. Create a PSC service attachment.
          2. Create an endpoint attachment and then enter the details of the endpoint attachment in the Host address field.
        2. If you want to establish a public connection to your backend systems with additional security, you can consider configuring static outbound IP addresses for your connections, and then configure your firewall rules to allowlist only the specific static IP addresses.

      To enter additional destinations, click +Add destination.

    2. Click Next.
  6. In the Authentication section, enter the authentication details.
    1. Select any of the following Authentication type, and then enter the corresponding details.
      • Windows credentials: Select this if you are using on-premise edition of SharePoint. Then, do the following:
        1. Username: Enter the username.
        2. Password: Select the password.
        3. Secret version: Enter the secret version.
      • AzureAD: Select this if you are using online edition of Sharepoint. Then, do the following:
        1. Client ID: Enter the client ID that is used for requesting access tokens. You can get the client ID by configuring the SharePoint app in Azure AD.
        2. Scopes: Enter a comma-separated list of desired scopes. For example, Sites.FullControl.All
        3. Client secret: Enter the secret that contains the client secret for the connected app that you created.
        4. Secret version: Secret version for the secret selected above.
        5. Authorization URL: Authorization URL generated when creating the client. Enter the URL in the following format: https://login.microsoftonline.com/<tenant_identifier>/oauth2/v2.0/authorize. For example, https://login.microsoftonline.com/9bxxxxxxxxx8112/oauth2/v2.0/authorize.
    2. Click Next.
  7. Review: Review your connection and authentication details.
  8. Click Create.

Entities, operations, and actions

All the Integration Connectors provide a layer of abstraction for the objects of the connected application. You can access an application's objects only through this abstraction. The abstraction is exposed to you as entities, operations, and actions.

  • Entity: An entity can be thought of as an object, or a collection of properties, in the connected application or service. The definition of an entity differs from a connector to a connector. For example, in a database connector, tables are the entities, in a file server connector, folders are the entities, and in a messaging system connector, queues are the entities.

    However, it is possible that a connector doesn't support or have any entities, in which case the Entities list will be empty.

  • Operation: An operation is the activity that you can perform on an entity. You can perform any of the following operations on an entity:

    Selecting an entity from the available list, generates a list of operations available for the entity. For a detailed description of the operations, see the Connectors task's entity operations. However, if a connector doesn't support any of the entity operations, such unsupported operations aren't listed in the Operations list.

  • Action: An action is a first class function that is made available to the integration through the connector interface. An action lets you make changes to an entity or entities, and vary from connector to connector. However, it is possible that a connector doesn't support any action, in which case the Actions list will be empty.

Actions

This section lists some of the actions supported by the connector. To understand how to configure the actions, see Action examples.

DeleteAttachment action

This action deletes an attachment.

Input parameters of the DeleteAttachment action

Parameter name Data type Required Description
ListTitle String Yes Title of the list item.
ItemId String Yes ID of the list item.
FileName String Yes Name of the file to be deleted from the document library.

To understand how to configure the DeleteAttachment action, see Action examples.

CheckInDocument action

This action lets you check in a document.

Input parameters of the CheckInDocument action

Parameter name Data type Required Description
RelativeURL String Yes Relative URL of the folder.
DocumentName String Yes Name of the file to be checked in.
Comment String No An optional check in message.

To understand how to configure the CheckInDocument action, see Action examples.

ChekOutDocument action

This action lets you check out a file.

Input parameters of the ChekOutDocument action

Parameter name Data type Required Description
RelativeURL String Yes Relative URL of the folder.
DocumentName String Yes Name of the file to be checked out.

To understand how to configure the ChekOutDocument action, see Action examples.

DiscardCheckOutDocument action

This action lets you undo a file check out.

Input parameters of the DiscardCheckOutDocument action

Parameter name Data type Required Description
RelativeURL String Yes Relative URL of the folder.
DocumentName String Yes Name of the file for which the check out has to be undone.

To understand how to configure the DiscardCheckOutDocument action, see Action examples.

CopyDocument action

This action lets you copy a file from one location to another location.

Input parameters of the CopyDocument action

Parameter name Data type Required Description
SourceFileRelativeUrl String Yes Relative URL of the source file.
DestFileRelativeUrl String Yes Relative URL of the destination file.

To understand how to configure the CopyDocument action, see Action examples.

UploadDocument action

This action lets you upload a file.

Input parameters of the UploadDocument action

Parameter name Data type Required Description
FileName String Yes Name of the file to be uploaded.
RelativeUrl String Yes Relative URL of the folder.
Content String No Content to upload as a file.
ContentBytes String No Bytes content (as a Base64 string) to upload as a file. Use this to upload binary data.
HasBytes Boolean No Specifies if the content to be uploaded is binary. The default value is false.

To understand how to configure the UploadDocument action, see Action examples.

DownloadDocument action

This action lets you download a file.

Input parameters of the DownloadDocument action

Parameter name Data type Required Description
RemoteFile String Yes Full URL of the file to download.
Library String Yes Name of the library on the SharePoint server.
HasBytes Boolean No Specifies if the content should be downloaded as bytes. The default value is false.

To understand how to configure the DownloadDocument action, see Action examples.

MoveAttachmentOrDocument action

This action lets you move a file from one folder to another folder.

Input parameters of the MoveAttachmentOrDocument action

Parameter name Data type Required Description
SourceFileURL String Yes URL of the source file that should be moved.
DestinationFolderURL String Yes URL of the destination folder.

To understand how to configure the MoveAttachmentOrDocument action, see Action examples.

CreateFolder action

This action lets you create a folder.

Input parameters of the CreateFolder action

Parameter name Data type Required Description
RelativeURL String Yes Relative URL of the folder.
FolderName String Yes Name of the folder to create.

To understand how to configure the CreateFolder action, see Action examples.

AddAttachments action

This action lets you add an attachment.

Input parameters of the AddAttachments action

Parameter name Data type Required Description
ListTitle String Yes Name of the attachment list.
FileName String Yes Name of the attachment file.
ItemId String Yes ID of the attachment to be added.
Content String Yes Content of the attachment.
ContentBytes String No Bytes content (as a Base64 string) to upload as an attachment. Use this to upload binary data.
HasBytes Boolean No Specifies if the content to be uploaded is binary. The default value is false.

To understand how to configure the AddAttachments action, see Action examples.

DownloadAttachments action

This action lets you download attachments.

Input parameters of the DownloadAttachments action

Parameter name Data type Required Description
RemoteFile String Yes Relative URL of the file.
HasBytes Boolean No Specifies if the content to be downloaded is binary. The default value is false.

To understand how to configure the DownloadAttachments action, see Action examples.

Action examples

This section describes how to perform some of the actions in this connector.

Example - Delete an attachment

This example deletes the specified file.

  1. In the Configure connector task dialog, click Actions.
  2. Select the DeleteAttachment action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"ListTitle": "My lists",
"ItemId": "1",
"FileName": "sitepages.txt"
}

    4. If the action is successful, the DeleteAttachment task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Status": "Success"
}]

Example - Check in a document

This example checks in a document.

  1. In the Configure connector task dialog, click Actions.
  2. Select the CheckInDocument action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"RelativeURL": "/Shared Documents/TestFolder",
"DocumentName": "Document.txt",
"Comment": "Comment test"
}

    4. If the action is successful, the CheckInDocument task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Status": "Success"
}]

Example - Chek out a file

This example checks out a file.

  1. In the Configure connector task dialog, click Actions.
  2. Select the ChekOutDocument action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"RelativeURL": "/Shared Documents/TestFolder",
"DocumentName": "Document.txt"
}

    4. If the action is successful, the ChekOutDocument task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Status": "Success"
}]

Example - Discard a check out

This example reverts a file check out.

  1. In the Configure connector task dialog, click Actions.
  2. Select the DiscardCheckOutDocument action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"RelativeURL": "/Shared Documents/TestFolder",
"DocumentName": "Document.docx"
}

    4. If the action is successful, the DiscardCheckOutDocument task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Status": "Success"
}]

Example - Copy a file

This example copies a file from one location to another location.

  1. In the Configure connector task dialog, click Actions.
  2. Select the CopyDocument action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"SourceFileRelativeUrl": "/Shared Documents/Document.docx",
"DestFileRelativeUrl": "/Shared Documents/TestFolder/Document123.docx"
}

    4. If the action is successful, the CopyDocument task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Status": "Success"
}]

Example - Upload a text file

This example uploads a text file to the specified location.

  1. In the Configure connector task dialog, click Actions.
  2. Select the UploadDocument action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"FileName": "test.txt",
"RelativeUrl": "/Shared Documents/TestFolder",
"Content": "abcd"
}

    4. If the action is successful, the UploadDocument task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Status": "Success"
}]

Example - Upload a binary file

This example uploads a binary file to the specified location. When uploading a binary file, specify the content to upload as a Base64 encoded string.

  1. In the Configure connector task dialog, click Actions.
  2. Select the UploadDocument action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"FileName": "test.txt",
"RelativeUrl": "/Shared Documents/TestFolder",
"ContentBytes": "SGVsbG8gd29ybGQK",
"HasBytes": "true"
}

    4. If the action is successful, the UploadDocument task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Status": "Success"
}]

Example - Download a file

This example downloads a file.

  1. In the Configure connector task dialog, click Actions.
  2. Select the DownloadDocument action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"RemoteFile": "/TestFolder/test.txt",
"Library": "Shared Documents"
}

    4. If the action is successful, the DownloadDocument task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Success": "True",
"Content": "Test File",
}]

Example - Download a binary file

This example downloads a binary file.

  1. In the Configure connector task dialog, click Actions.
  2. Select the DownloadDocument action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"RemoteFile": "/TestFolder/test1.png",
"Library": "Shared Documents"
"HasBytes": "true"  
}

    4. If the action is successful, the DownloadDocument task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Success": "True",
"ContentBytes": "VGVzdCBGaWxl",
}]

Example - Move an attachment

This example moves an attachment from one location to another location.

  1. In the Configure connector task dialog, click Actions.
  2. Select the MoveAttachmentOrDocument action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"SourceFileURL": "/Shared Documents/test.txt",
"DestinationFolderURL": "/Shared Documents/TestFolder"
}

    4. If the action is successful, the MoveAttachmentOrDocument task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Result": "Success"
}]

Example - Create a folder

This example creates a folder in the specified location.

  1. In the Configure connector task dialog, click Actions.
  2. Select the CreateFolder action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"RelativeURL": "/Shared Documents/TestFolder",
"FolderName": "TestFolder123"
}

    4. If the action is successful, the CreateFolder task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Id": "110842b7-2393-4f11-9391-3d75214e9fb8",
"Status": "Success"
}]

Example - Add an attachment

This example adds an attachment to the specified list.

  1. In the Configure connector task dialog, click Actions.
  2. Select the AddAttachments action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"ListTitle": "My Lists",
"FileName": "TestAttachment2",
"Content": "abcd text",
"ItemId": "1"
}

    4. If the action is successful, the AddAttachments task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"RelativeUrl": "/Lists/My lists/Attachments/1/TestAttachment2",
"Status": "Success"
}]

Example - Add a binary attachment

This example adds a binary attachment to the specified list.

  1. In the Configure connector task dialog, click Actions.
  2. Select the AddAttachments action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"ListTitle": "My Lists",
"FileName": "TestAttachment3",
"ContentBytes": "VGVzdCBGaWxl",
"HasBytes": "true",  
"ItemId": "1"
}

    4. If the action is successful, the AddAttachments task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"RelativeUrl": "/Lists/My lists/Attachments/1/TestAttachment3",
"Status": "Success"
}]

Example - Download an attachment

This example downloads an attachment.

  1. In the Configure connector task dialog, click Actions.
  2. Select the DownloadAttachments action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"RemoteFile": "/Shared Documents/Document.txt"
}

    4. If the action is successful, the DownloadAttachments task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Success": "True",
"Content": "Test File",
}]

Example - Download a binary attachment

This example downloads a binary attachment.

  1. In the Configure connector task dialog, click Actions.
  2. Select the DownloadAttachments action, and then click Done.
  3. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"RemoteFile": "/Shared Documents/Document.docx",
"HasBytes": "true"
}

    4. If the action is successful, the DownloadAttachments task's connectorOutputPayload response parameter will have a value similar to the following:

    [{
"Success": "True",
"ContentBytes": "VGVzdCBGaWxl",
}]

Entity operation examples

This section shows how to perform some of the entity operations in this connector.

Example - List all files

This example lists all the files in the Files entity.

  1. In the Configure connector task dialog, click Entities.
  2. Select Files from the Entity list.
  3. Select the List operation, and then click Done.
  4. Optionally, in Task Input section of the Connectors task, you can filter your result set by specifying a filter clause. You can also specify multiple filter conditions by using the logic operators.

Example - Get a list

This example gets a list with the specified ID from the My Lists entity.

  1. In the Configure connector task dialog, click Entities.
  2. Select My Lists from the Entity list.
  3. Select the Get operation, and then click Done.
  4. In the Task Input section of the Connectors task, click EntityId and then enter 3 in the Default Value field.

    Here, 3 is a primary key value in the My Lists entity.

Example - Create a record

This example creates a record in the My Lists entity.

  1. In the Configure connector task dialog, click Entities.
  2. Select My Lists from the Entity list.
  3. Select the Create operation, and then click Done.
  4. In the Task Input section of the Connectors task, click connectorInputPayload and then enter a value similar to the following in the Default Value field: 
    {
"AuthorId": 11.0, 
"BaseName": "3_",
"Attachments": false,
"Title": "Created List New"
}

    If the integration is successful, your connector task's connectorOutputPayload field will have a value similar to the following:

    [{
"ID": 3.0
}]

Example - Delete a record

This example deletes the record with the specified ID in the My Lists entity.

  1. In the Configure connector task dialog, click Entities.
  2. Select My Lists from the Entity list.
  3. Select the Delete operation, and then click Done.
  4. In the Task Input section of the Connectors task, click entityId and then enter 2 in the Default Value field.

Use the SharePoint connection in an integration

After you create the connection, it becomes available in both Apigee Integration and Application Integration. You can use the connection in an integration through the Connectors task.

  • To understand how to create and use the Connectors task in Apigee Integration, see Connectors task.
  • To understand how to create and use the Connectors task in Application Integration, see Connectors task.

Get help from the Google Cloud community

You can post your questions and discuss this connector in the Google Cloud community at Cloud Forums.

What's next