Commonly Occurring Errors in Microsoft Graph Integrations and How To Troubleshoot Them (Part 7)

Retrieving attachments from SharePoint lists is a key feature when integrating data from SharePoint into external applications. Microsoft offers two possible APIs: the SharePoint REST API and the Microsoft Graph API. Both approaches provide methods to access the desired data. We explain the steps for configuring and using these APIs to retrieve attachments from a SharePoint list.

SharePoint Lists

SharePoint provides different list types to suit various data management needs and applications.

Standard Lists

Standard lists allow for customization and flexibility. A custom list offers a blank template that can be tailored to specific requirements. At the same time, the datasheet view resembles an Excel table, making it ideal for quick and efficient data editing.

Specialized Lists

Specialized lists come preconfigured for specific purposes. For example, announcements display important messages or updates, while task lists help manage tasks with features like due dates, statuses, and responsibilities. Calendars facilitate the scheduling of appointments and events, and contact lists, such as address books, are perfect for storing and sharing contact information. Discussion boards enable the creation of forums for team collaboration, link lists store and organize hyperlinks, surveys gather and analyze feedback, and issue tracking lists provide a straightforward system for managing problems or bugs.

Document and Media Libraries

Although document and media libraries are not categorized as lists, they are deeply integrated into SharePoint. Document libraries are designed for file management, offering features such as version control and metadata tagging. Asset libraries cater to multimedia content, including images, videos, and audio files.

Advanced and External Lists

For more complex scenarios, SharePoint offers advanced and external lists. External lists connect to data from external systems via Business Connectivity Services (BCS), enabling seamless integration. Additionally, SharePoint allows for the creation of lists by importing Excel spreadsheets, automatically converting them into a SharePoint-compatible format. Catalog lists are useful for managing product or service information.

Modern Lists

Modern lists in SharePoint Online enhance traditional functionality with advanced features. They integrate with tools like Power Apps and Power Automate, enabling users to create custom workflows and forms. Furthermore, they support JSON-based customizations, offering personalized layouts and views for better user experiences.

SharePoint lists are highly versatile, supporting a range of use cases, including project management with task and calendar lists, CRM systems with contact and announcement lists, document management through libraries, and feedback collection with survey lists. Their flexibility and integration capabilities make them an essential tool for efficient data organization and collaboration.

Microsoft APIs

Microsoft provides several APIs for accessing SharePoint:

• The Microsoft Graph API is the recommended API for working with SharePoint Online and Office 365. It offers a modern, REST-based interface for seamless integration.
• The SharePoint REST API is available for both SharePoint Online and On-Premises, providing broader coverage for list operations.
• The CSOM (Client-Side Object Model) is frequently used in .NET applications or scripts and provides an object-oriented interface for interacting with SharePoint.
• The JSOM (JavaScript Object Model) is a client-side API specifically designed for JavaScript development in SharePoint.
• The PnP (Patterns and Practices) Library offers an abstracted, simplified interface for accessing SharePoint, making development more efficient.

The table below provides an overview of which API is best suited for different SharePoint list types:

Use Cases

The following examples focus on the SharePoint API and Microsoft Graph API. Before discussing individual examples, in the first step, an access token must be obtained for both APIs.

To acquire an access token for the Microsoft Graph API, a POST request must be sent to the Azure OAuth 2.0 token endpoint:

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token 
Content-Type: application/x-www-form-urlencoded 
client_id={client-id} 
client_secret={client-secret} 
grant_type=client_credentials 
scope=https://graph.microsoft.com/.default

The tenant ID refers to the directory ID from Azure AD. The client ID is the application ID obtained from the app registration. The client secret represents the generated client secret. The scope should be set towards https://graph.microsoft.com/.default (Microsoft Graph API) or https://{sharepoint-domain}/.default (SharePoint REST API).

To obtain an access token for the SharePoint API, the following HTTP POST request must be sent:  

POST https://accounts.accesscontrol.windows.net/{tenant-id}/tokens/OAuth/2
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id={client-id}@{tenant-id}
client_secret={client-secret}
resource=00000003-0000-0ff1-ce00-000000000000/{sharepoint-domain}@{tenant-id}

The grant_type should always be set to client_credentials for server-side applications. This client_id is the client ID of your app, followed by the tenant ID. The client_secret is the previously generated client secret. The resource is the resource you want to access. For the SharePoint REST API, the resource format is:

00000003-0000-0ff1-ce00-000000000000/{sharepoint-domain}@{tenant-id}

For example:

00000003-0000-0ff1-ce00-000000000000/contoso.sharepoint.com@{tenant-id}

Even with a valid SharePoint API access token, you may still encounter the following error message (return code 403):

{
    "error": {
        "code": "-2147024891, System.UnauthorizedAccessException",
        "message": {
            "lang": "en-US",
            "value": "Access is denied. (Exception from HRESULT: 0x80070005 (E_ACCESSDENIED))"
        }
    }
}

This suggests that not all required permissions have been correctly assigned to the Azure app. The following permissions should be granted to use the SharePoint API:

• Sites.Read.All (Read SharePoint sites)
• Sites.Manage.All (Manage sites)
• Sites.FullControl.All (Full control over all sites)

Once all the necessary permissions are granted and a valid access token is obtained, you can retrieve attachments from SharePoint lists.

Now, let's look at the different types of SharePoint lists and how attachments for each list type can be downloaded via an API.

Assuming you want to retrieve the attachment of a document library item, the article provides the following approach: Commonly Occurring Errors in Microsoft Graph Integrations and How To Troubleshoot Them, a corresponding guide. 

In the next example, we will download an attachment from a SharePoint list of type GenericList. To retrieve an attachment from a list item, the following GET request must be sent:

GET https://{tenant}.sharepoint.com/sites/{site-name}/_api/web/lists/GetByTitle('{list-name}')/items({item-id})/AttachmentFiles
Authorization: Bearer {access-token}
Accept: application/json;odata=verbose

The response should look something like this:

{
  "d": {
    "results": [
      {
        "FileName": "example.txt",
        "ServerRelativeUrl": "/sites/{site-name}/Lists/{list-name}/Attachments/{item-id}/example.txt"
      }
    ]
  }
}

Use the ServerRelativeUrl to download the attachment directly. The following request will download the file:

GET https://{tenant}.sharepoint.com/sites/{site-name}/Lists/{list-name}/Attachments/{item-id}/example.txt
Authorization: Bearer {access-token}

The content of the HTTP response is the file itself, encoded in the content bytes. You should save the response body to process the file in your desired format (e.g., as byte[] in Java or as a file).

Issues and Challenges

Different List Types

Document libraries and custom lists have different data structures and attachment management methods. Attachments are often part of document metadata in document libraries, while in custom lists, attachments are stored in separate fields. These differences make it difficult to retrieve attachments using a unified API or method.

Access Control

Access to lists and their attachments depends on the user's permissions. Issues can arise when the requesting user lacks sufficient permissions to access the attachments. The hierarchical structure of SharePoint sites and collections can also introduce additional complexities.

API Complexity

The Microsoft Graph API and the SharePoint REST API provide options for accessing lists and their attachments. However, there are differences in how attachments are retrieved. While the API for document libraries is specifically designed to manage documents and their versions, accessing attachments in custom lists often requires additional requests and logic.

Performance Issues

Retrieving attachments from large lists or libraries can lead to performance problems, especially when many attachments or large files are involved. Timeouts can also occur if the API requests are not properly optimized.

Conclusion

Working with SharePoint lists and retrieving attachments from various lists is complex and challenging. SharePoint offers a variety of list types, including document libraries, custom lists, and lists specifically used for tasks, calendars, or discrete information. Each of these lists may implement different mechanisms for adding, managing, and retrieving attachments, which leads to varying challenges when automating the process of retrieving these attachments.