Establishing a Connection
Enabling SSIS in Visual Studio 2022
If you're using Visual Studio 2022, you will need to install the SQL Server Integration Services Projects extension to use SSIS.
- Navigate to Extensions > Manage Extensions.
- In the Manage Extensions window's search box, search for "SQL Server Integration Services Projects 2022" and select the extension in the list.
- Click Download.
- Close Visual Studio and run the downloaded Microsoft.DataTools.IntegrationServices.exe installer. Proceed through the installer with default settings.
- Open Visual Studio. There should now be an "Integration Services Project" project template available.
Adding the Microsoft Excel Online Connection Manager
Create a new connection manager as follows:
- Create a Visual Studio project with the "Integration Services Project" template.
- In the project, right-click within the Connection Managers window and select New Connection from the menu.
- In the Description column, select CData Microsoft Excel Online Connection Manager and click Add...
- Configure the component as described in the next section.
Alternatively, if you have an existing project and CData Microsoft Excel Online Source or CData Microsoft Excel Online Destination:
- Right-click your CData Microsoft Excel Online source or destination component in your data flow
- Select Edit... to open an editor window.
- Click the New... button next to the Connection manager: dropdown selector to create a connection manager.
- Configure the component as described in the next section.
Connecting to Microsoft Excel Online
There are two authentication methods available for connecting to Microsoft Excel Online data source:
- OAuth 2.0-based methods: Microsoft Excel Online provides OAuth 2.0-based authentication via both Azure AD and Azure Service Principal.
- For Azure AD authentication, set AuthScheme to AzureAD.
- For Azure Service Principal authentication, set AuthScheme to AzureServicePrincipal.
- Managed Service Identity (MSI) authentication. To use this method, set AuthScheme to AzureMSI.
Azure AD
Azure AD is user-based authentication. Credentials are supplied to connect AzureAD to Microsoft Excel Online via a Desktop application. To use the embedded credentials for authentication, leave the OAuth credentials (OAuthClientId and OAuthClientSecret) blank.
For connecting via a Web application, you must create a custom OAuth Azure AD application. The creation of a Custom Azure AD application establishes the OAuth credentials OAuthClientId and OAuthClientSecret. For a discussion of how to create a custom Azure AD application, and reasons why that might be advantageous even if you are not connecting via a Web application, see Creating an Azure AD Application.
Azure Service Principal
The authentication as an Azure Service Principal is handled via the OAuth Client Credentials flow. It does not involve direct user authentication. Instead, credentials are created for just the application itself. All tasks taken by the app are done without a default user context, but based on the assigned roles. The application access to the resources is controlled through the assigned roles' permissions.
Create an AzureAD App and an Azure Service Principal
When authenticating using an Azure Service Principal, you must create and register an Azure AD application with an Azure AD tenant. See Creating an Azure AD Application for more details.
In your App Registration in portal.azure.com, navigate to API Permissions and select the Microsoft Graph permissions. There are two distinct sets of permissions: Delegated permissions and Application permissions. The permissions used during client credential authentication are under Application Permissions.
Assign a role to the application
To access resources in your subscription, you must assign a role to the application.
- Open the Subscriptions page by searching and selecting the Subscriptions service from the search bar.
- Select the subscription to assign the application to.
- Open the Access control (IAM) and select Add > Add role assignment to open the Add role assignment page.
- Select Owner as the role to assign to your created Azure AD app.
Client Secret
Set these connection properties:
- AuthScheme: AzureServicePrincipal to use a client secret.
- InitiateOAuth: GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
- AzureTenant: The tenant you want to connect to.
- OAuthClientId: The client Id in your application settings.
- OAuthClientSecret: The client secret in your application settings.
Certificate
Set these connection properties:
- AuthScheme: AzureServicePrincipalCert to use a certificate.
- InitiateOAuth: GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
- AzureTenant: The tenant you want to connect to.
- OAuthJWTCert: The JWT Certificate store.
- OAuthJWTCertType: The type of the certificate store specified by OAuthJWTCert.
You are now ready to connect. Authentication with client credentials takes place automatically like any other connection, except there is no window opened prompting the user. Because there is no user context, there is no need for a browser popup. Connections take place and are handled internally.
Managed Service Identity (MSI)
If you are running Microsoft Excel Online on an Azure VM and want to leverage MSI to connect, set AuthScheme to AzureMSI.
User-Managed Identities
To obtain a token for a managed identity, use the OAuthClientId property to specify the managed identity's "client_id".When your VM has multiple user-assigned managed identities, you must also specify OAuthClientId.
Connecting to a Workbook
The component exposes workbooks and worksheets from drives you specify in your Microsoft account. You can connect to a workbook by providing authentication to Excel Online and setting any of the following properties.
To control which drives are discovered:
- Drive: The ID of a specific drive. You can use the Drives and SharePointSites views to view all the sites and drives you have access to.
- SharepointURL: The browser URL of a SharePoint site. The driver will expose all drives under the site.
- OAuthClientId: If AuthScheme is set to AzureServicePrincipal or if OAuthGrantType is set to CLIENT, the drive associated with your OAuth app will be exposed.
If none of the above are specified, access is restricted to the authenticated user's personal drive.
To control which workbooks and worksheets are exposed OR which drives are exposed:
- Workbook: The name or Id of the workbook. An authenticate user can view a list of information about the available workbooks by executing a query to the Workbooks view.
- UseSandbox: True to connect to a workbook in a sandbox account; otherwise, leave blank.
- BrowsableSchemas: A list of drive names to expose.
- Tables: A list of table names to expose.
Executing SQL Against Worksheet Data
For information on how to execute data manipulation SQL against worksheets and ranges, see:
- Selecting ExcelOnline Data
- Inserting ExcelOnline Data
- Updating ExcelOnline Data
- Deleting ExcelOnline Data
- Using Formulas
For details on how the component models worksheets and cells as tables and columns, See Data Model.
Retrieving Data from SharePoint Excel Files
To retrieve data from Sharepoint Excel files, set the SharepointURL connection property to the URL of your Sharepoint site. For example,SharepointURL=https://mysite.sharepoint.com/The driver automatically looks up each document library you have in SharePoint and lists it as a schema. Individual Excel workbooks and worksheets are listed as tables in the format Workbook_Worksheet under their corresponding document library. This works in the same manner as listing your own personal Excel documents when SharepointURL is not set.