With the CData Cmdlets users can install a data module, set the connection properties, and start scripting. This section provides examples of using our ExcelOnline Cmdlets with native PowerShell cmdlets, like the CSV import and export cmdlets.

Installing and Connecting

If you have PSGet, installing the cmdlets can be accomplished from the PowerShell Gallery with the following command. You can also obtain a setup from the CData site.

Install-Module ExcelOnlineCmdlets

The following line is then added to your profile, loading the cmdlets on the next session:

Import-Module ExcelOnlineCmdlets;

You can then use the Connect-ExcelOnline cmdlet to create a connection object that can be passed to other cmdlets:

$conn = Connect-ExcelOnline

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.

1. Open the Subscriptions page by searching and selecting the Subscriptions service from the search bar.
2. Select the subscription to assign the application to.
3. Open the Access control (IAM) and select Add > Add role assignment to open the Add role assignment page.
4. Select Owner as the role to assign to your created Azure AD app.

Complete the Authentication Choose whether to use a client secret or a certificate and follow the relevant steps below.

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 cmdlet 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 cmdlet 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.

Retrieving Data

The Select-ExcelOnline cmdlet provides a native PowerShell interface for retrieving data:

$results = Select-ExcelOnline -Connection $conn -Table "Test_xlsx_Sheet1" -Columns @("Id, Column1") -Where "Column2='Bob'"

The Invoke-ExcelOnline cmdlet provides an SQL interface. This cmdlet can be used to execute an SQL query via the Query parameter.

Piping Cmdlet Output

The cmdlets return row objects to the pipeline one row at a time. The following line exports results to a CSV file:

Select-ExcelOnline -Connection $conn -Table Test_xlsx_Sheet1 -Where "Column2 = 'Bob'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myTest_xlsx_Sheet1Data.csv -NoTypeInformation

You will notice that we piped the results from Select-ExcelOnline into a Select-Object cmdlet and excluded some properties before piping them into an Export-CSV cmdlet. We do this because the CData Cmdlets append Connection, Table, and Columns information onto each row object in the result set, and we do not necessarily want that information in our CSV file.

However, this makes it easy to pipe the output of one cmdlet to another. The following is an example of converting a result set to JSON:

 
PS C:\> $conn  = Connect-ExcelOnline
PS C:\> $row = Select-ExcelOnline -Connection $conn -Table "Test_xlsx_Sheet1" -Columns (Id, Column1) -Where "Column2 = 'Bob'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Test_xlsx_Sheet1",
  "Columns":  [

  ],
  "Id":  "MyId",
  "Column1":  "MyColumn1"
} 

Deleting Data

The following line deletes any records that match the criteria:

Select-ExcelOnline -Connection $conn -Table Test_xlsx_Sheet1 -Where "Column2 = 'Bob'" | Remove-ExcelOnline

Modifying Data

The cmdlets make data transformation easy as well as data cleansing. The following example loads data from a CSV file into Microsoft Excel Online, checking first whether a record already exists and needs to be updated instead of inserted.

Import-Csv -Path C:\MyTest_xlsx_Sheet1Updates.csv | %{
  $record = Select-ExcelOnline -Connection $conn -Table Test_xlsx_Sheet1 -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-ExcelOnline -Connection $conn -Table Test_xlsx_Sheet1 -Columns @("Id","Column1") -Values @($_.Id, $_.Column1) -Where "Id  = `'$_.Id`'"
  }else{
    Add-ExcelOnline -Connection $conn -Table Test_xlsx_Sheet1 -Columns @("Id","Column1") -Values @($_.Id, $_.Column1)
  }
}