- 1 Introduction
- 2 Prerequisites
- 3 Use Case of Microsoft Graph API
- 4 Register Application (OAuth2 App for Graph API)
- 5 Step-By-Step to Call Microsoft Graph Rest API Using SSIS
- 6 Conclusion
- 7 References
In our previous article, we saw How to Get Office 365 data in Power BI. Now let’s look at How to Get Office 365 Mail Attachments using SSIS without any coding. Microsoft Graph API is a unified way to access many Microsoft services API including Office 365 API. In this post, we will use SSIS JSON / REST API Source Connector to get the Outlook Messages list and get the attachments of those messages.
PrerequisitesBefore we perform steps listed in this article, you will need to make sure following prerequisites are met:
- SSIS designer installed. Sometimes it is referred as BIDS or SSDT (download it from Microsoft site).
- Basic knowledge of SSIS package development using Microsoft SQL Server Integration Services.
- Make sure ZappySys SSIS PowerPack is installed (download it).
- Optional (If you want to Deploy and Schedule ) - Deploy and Schedule SSIS Packages
Use Case of Microsoft Graph API
Here are some use cases why you want to use Microsoft Graph API
- Read/Write events from Outlook Calendar
- Send email / Read emails
- Get the list of files from OneDrive
- Upload/ Download files to OneDrive
- Read/Write Excel Sheet (Use range or a specific range of specific sheet)
- Read Sharepoint Document library
- Search content from Sharepoint document library
- Get AD users for your Organization (AD Accounts)
- Update OneNote
- Track changes to Users, Events, Calendar Items using delta API
Register Application (OAuth2 App for Graph API)
Very first step to access any Office 365 API / Graph API is to register OAuth App. It's a few step process. After following steps you will get following 2 items to use for next section.
- Application Id
- Application Secret
In this section, you will learn how to register a custom app in Microsoft Azure portal that will allow access to the OneDrive. So, let's get started -
- Log into Microsoft Azure portal to register a custom app.
- Register a new application by clicking New Registration link.
- Provide the name of the custom app and who can access the app in the organization.
- Go to the App overview and add a Redirect URL.
- Click on "Add a Platform" under Platform Configuration section and then select "Web" under Web applications
section to enter a Redirect URL.
- Create a Client Secret key which will be used to Authenticate the custom Azure app.
Note - Take a note of Client Secret, it will be required while configuring OAuth connection in the SSIS later
- Add API Permissions.
- Select following permissions from the Delegated Permissions section.
User.ReadBasic.All Files.Read offline_access
- Take a note of Client ID, it will be required while configuring OAuth connection in the SSIS later.
Step-By-Step to Call Microsoft Graph Rest API Using SSIS
Now let’s look at examples to access your outlook.com emails using SSIS. You can use the same techniques to call pretty much any Office 365 API.
Configure SSIS OAuth Connection for Graph REST API
The first step to access any Graph API is configured OAuth connection
- Open Visual Studio
- Open existing SSIS Project or create new using File > New > Project > Choose “Integration Services Project” Type under Business Intelligence template category
- Create Package
- Right-click inside the Connection Managers area and click “New Connection…”
- From the connection type list select “ZS-OAUTH” connection type.
- On the OAuth, Connection Manager configure the following options
- Select “Custom” from Provider dropdown
- Select OAuth2 from OAuth version
- Enter your Application Id and Secret Key (i.e. App Password) obtained in the previous section from here.
- Enter the following URL in the Authorization URL
- Use following URL in the token URL field
- Enter the following Graph API Scopes (each scope must be entered in a new line).
123user.readmail.readoffline_accessNOTE: Always include offline_access scope returns refreh_token which allows you to renew token without going through the login process again. For more information about which scopes needed always refer to the API help page (e.g. if you want to read mail using this API then you will see it says you can use Mail.Read or Mail.ReadWrite scope).
- Go to Advanced tab and enter the following URL in the Callback/Return URL (Assuming exact same URL used when you registered App in the previous section)
- Now go back to the first tab and click Generate Token. When prompted Login using your Personal Microsoft Account or Work Account (Office 365 or AD login)
- After login, you will see Accept option just click it. If things go right then you will see Access Token and Refresh Token fields will be populated.
- Once all configured you can click Test to make sure connection works.
Download the Messages Attachment Files from Outlook
Let’s start with an example. We use the SSIS JSON Source and Web API Destination components to make the call to Microsoft Graph Rest API.
- First of All, Drag and drop Data Flow Task from SSIS Toolbox and double click it to edit.
- From the SSIS toolbox drag and drop JSON Source on the data flow designer surface.
- Double click JSON Source and enter the following URL as below to Get Messages API call with search options to get the mails which have the attachments.
To customize URL with additional parameters check this help link. It’s a standard OData Protocol so you can leverage many common OData features (e.g. Use $top parameters to set pageSize. Default is 10 for List Mail but you can include more records per response by changing it such as …/messages?$top=50).
- Now let’s use Template Transform to set the URL using the message ID to make the Get attachment API call.
- Now we need to use Web API Destination to make the Get Attachment API call by message-id. Select the Input column for URL as that TemplateOutput.
- Now next step is to parse the JSON Response String of get attachment api call, for that we need to use JSON Parser. Select the input as Web PAI Destination ResponseText and use the below sample JSON string to configure the metadata(Columns).
- Now in the JSON Parser go-to columns Tab and set the contentBytes DataType as DT_IMAGE and increase others’ columns DT_WSTR length with 1000 and 1500. We set contentBytes to DT_IMAGE datatype its like varbinary(MAX) .
- Furthermore, on the next step, we need to use SSIS Derived Column to set the FilePath where we want to save the attachments and concat the local file path with the attachment name column.
- Finally, we need to use the Export Column Transform (Native) to export attachment bytes to a local file. It needs to know 2 upstream info Bytes and Target File Path.
- Make sure to attach the export column to some destination (e.g. Our ZS Trash Destination) else it might be removed by the engine while It will optimize the runtime And it may remove all transformations that don’t have Destination like deploying the package to SQL Server or if you set optimize in the Visual Studio.
- That’s it execute the package and it will download all the email attachments.
After all, In this article, we have learned how to make Microsoft Graph API Rest API call. We used SSIS JSON / REST API Connector to extract data from Outlook Mail using OAuth. Made the Get attachment API call using the Web API Destination and parsed the JSON response using the JSON Parser. And using Native SSIS Export Column we saved export attachment bytes to a local file. To explore many other scenarios not discussed in this article download SSIS PowerPack from here (includes 70+ Components).
Finally, you can use the following links for more information:
- Help File: JSON Source(REST API or File)
- Help File: Web API Destination
- Help File: JSON Parser Transform
- Overview of the Microsoft Graph API