From c75bc0b7e2cb5e3b847f2b2f3345c362db7f7fc4 Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Thu, 31 Oct 2024 13:06:46 -0700 Subject: [PATCH 1/5] Update REST deprecation note --- docs/outlook/use-rest-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/outlook/use-rest-api.md b/docs/outlook/use-rest-api.md index d68d3730cf..1209ce5deb 100644 --- a/docs/outlook/use-rest-api.md +++ b/docs/outlook/use-rest-api.md @@ -1,7 +1,7 @@ --- title: Use the Outlook REST APIs from an Outlook add-in description: Learn how to use the Outlook REST APIs from an Outlook add-in to get an access token. -ms.date: 02/12/2024 +ms.date: 11/05/2024 ms.topic: how-to ms.localizationpriority: medium --- @@ -11,9 +11,9 @@ ms.localizationpriority: medium The [Office.context.mailbox.item](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item) namespace provides access to many of the common fields of messages and appointments. However, in some scenarios an add-in may need to access data that isn't exposed by the namespace. For example, the add-in may rely on custom properties set by an outside app, or it needs to search the user's mailbox for messages from the same sender. In these scenarios, the [Outlook REST APIs](/outlook/rest) is the recommended method to retrieve the information. > [!IMPORTANT] -> **Outlook REST v2.0 and beta endpoints deprecation** +> **Outlook REST v2.0 and beta endpoints are deprecated** > -> The Outlook REST v2.0 and beta endpoints will be [fully deprecated on March 31, 2024](https://devblogs.microsoft.com/microsoft365dev/outlook-rest-api-v2-0-and-beta-endpoints-decommissioning-update/). However, privately released and AppSource-hosted add-ins are able to use the REST service until [extended support ends for Outlook 2019 on October 14, 2025](/lifecycle/end-of-support/end-of-support-2025). Traffic from these add-ins is automatically identified for exemption. This exemption also applies to new add-ins developed after the decommission date. +> The Outlook REST v2.0 and beta endpoints are now [deprecated](https://devblogs.microsoft.com/microsoft365dev/final-reminder-outlook-rest-api-v2-0-and-beta-endpoints-decommissioning/). However, privately released and AppSource-hosted add-ins are still able to use the REST service until [extended support ends for Outlook 2019 on October 14, 2025](/lifecycle/end-of-support/end-of-support-2025). Traffic from these add-ins is automatically identified for exemption. This exemption also applies to new add-ins developed after the decommission date. > > Although add-ins are able to use the REST service until 2025, we highly encourage you to migrate your add-ins to use [Microsoft Graph](/outlook/rest#outlook-rest-api-via-microsoft-graph). For guidance, see [Compare Microsoft Graph and Outlook REST API endpoints](/outlook/rest/compare-graph). From 0d2f9f708ea39bdd2d2795d10f98747681cc40d9 Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Wed, 25 Dec 2024 16:13:28 -0800 Subject: [PATCH 2/5] Draft MS Graph article --- docs/outlook/microsoft-graph.md | 45 +++++++++++++++++++++++++++++++++ docs/outlook/use-rest-api.md | 10 ++++---- 2 files changed, 50 insertions(+), 5 deletions(-) create mode 100644 docs/outlook/microsoft-graph.md diff --git a/docs/outlook/microsoft-graph.md b/docs/outlook/microsoft-graph.md new file mode 100644 index 0000000000..08428766c9 --- /dev/null +++ b/docs/outlook/microsoft-graph.md @@ -0,0 +1,45 @@ +--- +title: Use the Microsoft Graph REST API from an Outlook add-in +description: Learn how to use the Outlook mail REST API from an Outlook add-in with Microsoft Graph. +ms.date: 11/05/2024 +ms.topic: how-to +ms.localizationpriority: medium +--- + +# Use the Microsoft Graph REST API from an Outlook add-in + +The Outlook JS API provides access to retrieve the properties of messages and appointments and run operations on these items. However, there may be instances where the data you need isn't exposed through the API. For example, your add-in may need to implement single sign-on or identify messages in a user's mailbox that originated from the same sender. To get the information you need, use the [Outlook mail REST API](/graph/api/resources/mail-api-overview) through [Microsoft Graph](/graph/overview). + +## Getting started + +Before you can make calls to the Microsoft Graph API, you must first perform the following: + +1. [Register your add-in in the Azure portal](/graph/auth-register-app-v2). +1. [Request an access token from the Microsoft identity platform](/graph/auth-v2-user). + +For Office Add-ins, [nested app authentication (NAA)](../develop/enable-nested-app-authentication-in-your-add-in.md) is the recommended solution to request a token. + +[!INCLUDE [legacy-exchange-token-deprecation](../includes/legacy-exchange-token-deprecation.md)] + +## Call the Microsoft Graph API + +Once you have an access token, you can then use it to call Microsoft Graph. + +The Microsoft Graph API consists of the v1.0 and beta endpoints. Note the following about the endpoint pattern. + +- `version` specifies the `v1.0` or `beta` API. +- `resource` specifies the resource your add-in interacts with, such as a user, group, or site. +- `query_parameters` specifies parameters to customize your request. For example, you can filter the messages returned to only those from a specific sender. + +```http +https://graph.microsoft.com/[version]/[resource]?[query_parameters] +``` + +For more information on Microsoft Graph API calls and its components, see [Use the Microsoft Graph API](/graph/use-the-api). + +## See also + +- [Microsoft Graph REST API v1.0 endpoint reference](/graph/api/overview) +- [Outlook mail API overview](/graph/outlook-mail-concept-overview) +- [Use the Outlook mail REST API](/graph/api/resources/mail-api-overview) +- [Enable SSO in an Office Add-in using nested app authentication (preview)](../develop/enable-nested-app-authentication-in-your-add-in.md) diff --git a/docs/outlook/use-rest-api.md b/docs/outlook/use-rest-api.md index 1209ce5deb..2ab10f33db 100644 --- a/docs/outlook/use-rest-api.md +++ b/docs/outlook/use-rest-api.md @@ -1,7 +1,7 @@ --- title: Use the Outlook REST APIs from an Outlook add-in description: Learn how to use the Outlook REST APIs from an Outlook add-in to get an access token. -ms.date: 11/05/2024 +ms.date: 01/09/2025 ms.topic: how-to ms.localizationpriority: medium --- @@ -13,9 +13,9 @@ The [Office.context.mailbox.item](/javascript/api/requirement-sets/outlook/previ > [!IMPORTANT] > **Outlook REST v2.0 and beta endpoints are deprecated** > -> The Outlook REST v2.0 and beta endpoints are now [deprecated](https://devblogs.microsoft.com/microsoft365dev/final-reminder-outlook-rest-api-v2-0-and-beta-endpoints-decommissioning/). However, privately released and AppSource-hosted add-ins are still able to use the REST service until [extended support ends for Outlook 2019 on October 14, 2025](/lifecycle/end-of-support/end-of-support-2025). Traffic from these add-ins is automatically identified for exemption. This exemption also applies to new add-ins developed after the decommission date. +> The Outlook REST v2.0 and beta endpoints are now [deprecated](https://devblogs.microsoft.com/microsoft365dev/final-reminder-outlook-rest-api-v2-0-and-beta-endpoints-decommissioning/). However, privately released and AppSource-hosted add-ins are still able to use the REST service until [extended support ends for Outlook 2019 on October 14, 2025](/lifecycle/end-of-support/end-of-support-2025). Traffic from these add-ins is automatically identified for exemption. This exemption also applies to new add-ins developed after March 31, 2024. > -> Although add-ins are able to use the REST service until 2025, we highly encourage you to migrate your add-ins to use [Microsoft Graph](/outlook/rest#outlook-rest-api-via-microsoft-graph). For guidance, see [Compare Microsoft Graph and Outlook REST API endpoints](/outlook/rest/compare-graph). +> Although add-ins are able to use the REST service until 2025, we highly encourage you to migrate your add-ins to use [Microsoft Graph](microsoft-graph.md). ## Get an access token @@ -117,5 +117,5 @@ function getCurrentItem(accessToken) { ## See also -- For an example that calls the REST APIs from an Outlook add-in, see [command-demo](https://github.com/OfficeDev/outlook-add-in-command-demo) on GitHub. -- Outlook REST APIs are also available through the Microsoft Graph endpoint but there are some key differences, including how your add-in gets an access token. For more information, see [Outlook REST API via Microsoft Graph](/outlook/rest/index#outlook-rest-api-via-microsoft-graph). +- [Add-in Command sample](https://github.com/OfficeDev/outlook-add-in-command-demo) +- [Use the Microsoft Graph REST API from an Outlook add-in](microsoft-graph.md) From 7fb5f2624959c71eb3f14ab5c114212529d3ef8f Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Tue, 28 Jan 2025 15:02:23 -0800 Subject: [PATCH 3/5] Apply minor fixes --- docs/outlook/microsoft-graph.md | 4 ++-- docs/outlook/use-rest-api.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/outlook/microsoft-graph.md b/docs/outlook/microsoft-graph.md index 08428766c9..152348b22b 100644 --- a/docs/outlook/microsoft-graph.md +++ b/docs/outlook/microsoft-graph.md @@ -1,14 +1,14 @@ --- title: Use the Microsoft Graph REST API from an Outlook add-in description: Learn how to use the Outlook mail REST API from an Outlook add-in with Microsoft Graph. -ms.date: 11/05/2024 +ms.date: 01/30/2025 ms.topic: how-to ms.localizationpriority: medium --- # Use the Microsoft Graph REST API from an Outlook add-in -The Outlook JS API provides access to retrieve the properties of messages and appointments and run operations on these items. However, there may be instances where the data you need isn't exposed through the API. For example, your add-in may need to implement single sign-on or identify messages in a user's mailbox that originated from the same sender. To get the information you need, use the [Outlook mail REST API](/graph/api/resources/mail-api-overview) through [Microsoft Graph](/graph/overview). +With the Outlook JavaScript API, you can retrieve the properties of messages and appointments and run operations on these items in your add-in. However, there may be instances where the data you need isn't exposed through the API. For example, your add-in may need to implement single sign-on or identify messages in a user's mailbox that originated from the same sender. To get the information you need, use the [Outlook mail REST API](/graph/api/resources/mail-api-overview) through [Microsoft Graph](/graph/overview). ## Getting started diff --git a/docs/outlook/use-rest-api.md b/docs/outlook/use-rest-api.md index 2ab10f33db..9c17c5d8ad 100644 --- a/docs/outlook/use-rest-api.md +++ b/docs/outlook/use-rest-api.md @@ -1,7 +1,7 @@ --- title: Use the Outlook REST APIs from an Outlook add-in description: Learn how to use the Outlook REST APIs from an Outlook add-in to get an access token. -ms.date: 01/09/2025 +ms.date: 01/30/2025 ms.topic: how-to ms.localizationpriority: medium --- From 3ab6ced1465c99e6672e5f177bb74caf5d8d1e41 Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Tue, 28 Jan 2025 15:06:52 -0800 Subject: [PATCH 4/5] Update TOC --- docs/toc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/toc.yml b/docs/toc.yml index d8e4b5d483..d13a9ae140 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -748,6 +748,8 @@ items: href: outlook/extension-module-outlook-add-ins.md - name: On-send add-ins href: outlook/outlook-on-send-addins.md + - name: Call the Microsoft Graph API + href: outlook/microsoft-graph.md - name: Call Outlook REST APIs href: outlook/use-rest-api.md - name: Call Exchange web services From 30814afdca580de57a1b6cd054c204e605cb5fe1 Mon Sep 17 00:00:00 2001 From: Sam Ramon <15154970+samantharamon@users.noreply.github.com> Date: Tue, 28 Jan 2025 17:51:20 -0800 Subject: [PATCH 5/5] Apply suggestions from review Co-authored-by: Linda Cannon --- docs/outlook/microsoft-graph.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/outlook/microsoft-graph.md b/docs/outlook/microsoft-graph.md index 152348b22b..b5a1099f67 100644 --- a/docs/outlook/microsoft-graph.md +++ b/docs/outlook/microsoft-graph.md @@ -10,7 +10,7 @@ ms.localizationpriority: medium With the Outlook JavaScript API, you can retrieve the properties of messages and appointments and run operations on these items in your add-in. However, there may be instances where the data you need isn't exposed through the API. For example, your add-in may need to implement single sign-on or identify messages in a user's mailbox that originated from the same sender. To get the information you need, use the [Outlook mail REST API](/graph/api/resources/mail-api-overview) through [Microsoft Graph](/graph/overview). -## Getting started +## Get started Before you can make calls to the Microsoft Graph API, you must first perform the following: @@ -35,7 +35,7 @@ The Microsoft Graph API consists of the v1.0 and beta endpoints. Note the follow https://graph.microsoft.com/[version]/[resource]?[query_parameters] ``` -For more information on Microsoft Graph API calls and its components, see [Use the Microsoft Graph API](/graph/use-the-api). +For more information on the Microsoft Graph API and its components, see [Use the Microsoft Graph API](/graph/use-the-api). ## See also