{"id":6571,"date":"2021-08-04T08:45:44","date_gmt":"2021-08-04T15:45:44","guid":{"rendered":"https:\/\/officedevblogs.wpengine.com\/?p=6571"},"modified":"2021-12-06T13:58:07","modified_gmt":"2021-12-06T21:58:07","slug":"breaking-changes-to-the-microsoft-graph-connectors-api-beta","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/breaking-changes-to-the-microsoft-graph-connectors-api-beta\/","title":{"rendered":"Breaking changes to the Microsoft Graph connectors API (beta)"},"content":{"rendered":"

We recognize that organizations have a wealth of data in other third-party services and applications. Boundary-less search is only as good as the sources it can access. Last year, we announced a public preview of Microsoft Graph connectors for customers and partners to index content into Microsoft Search. This enabled our customers to add content from several third-party services and applications into Microsoft Graph and make that content searchable in multiple Microsoft 365 search experiences.<\/p>\n

Thanks to your feedback during our preview, we have added several enhancements, including granular permissions; cleaner type names; simpler acl<\/strong> and identity<\/strong> types; security trimming on groups (and group-like constructs) in external systems; fine tuning of connection schema, even after set up; support for new experiences such as intelligent discovery and eDiscovery; and the ability to supply the default settings (such as the Adaptive Card display templates) for these experiences, with many more to come.<\/p>\n

We have also improved our API shape based on your feedback, to make it more useful and intuitive to developers. Implementing these improvements requires us to introduce some breaking changes.<\/p>\n

New fine-grained permissions<\/h4>\n

During the initial preview, we introduced the permission ExternalItem.ReadWrite.All for applications to create and manage connections as well ingest content into connections that they created (or were explicitly authorized to). Now, we are introducing more fine-grained permissions for customers to control access to their connector content.<\/p>\n\n\n\n\n\n\n\n
Permission<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n<\/thead>\n
ExternalConnection.ReadWrite.OwnedBy<\/td>\nThis permission allows an application to create new connections or manage existing connections, as well as their settings for any connection that the application created, or was explicitly authorized to use.<\/td>\n<\/tr>\n
ExternalItem.ReadWrite.OwnedBy<\/td>\nWith this permission, an application can read\/write content (external items) into all connections that the application created or was explicitly authorized to use.<\/td>\n<\/tr>\n
ExternalItem.ReadWrite.All<\/td>\nApplications with this permission can read\/write content (external items) into any connection within the Microsoft 365 tenant. Moreover, these applications will lose the ability to create and manage connections.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

We recommend that you choose the permission that works best for your use case. Requesting the least or the right privilege for your application will help improve the chances that an application or global admin will grant admin consent to your app.<\/p>\n

Introducing a new Microsoft Graph schema subnamespace<\/h4>\n

We introduced a dedicated schema subnamespace (microsoft.graph.externalConnectors) to provide clean and simple type names to all Microsoft Graph connector entities. If you have been using Microsoft Graph APIs with the connector entities in the global namespace (microsoft.graph), we recommend that you update your apps to either drop the OData type annotation for Microsoft Graph connector entities from their request payload and nested properties, or update it to the new namespace.<\/p>\n

\"Code<\/p>\n

Note that this change applies to all the connector entities. If you used the Microsoft Graph SDK to build your app, make sure to update it to use the latest SDK, and also update all code references to use the new subnamespace.<\/p>\n

Updates to resource types and properties<\/h4>\n

Simplified acl resource type<\/strong><\/p>\n

We are simplifying the \u00a0acl<\/strong> resource type by deprecating the identitySource <\/strong>property and rolling the values into the type <\/strong>property. The supported values for the type <\/strong>of acl <\/strong>are `user`, `group`, `everyone`, `everyoneExceptGuests`, and with this change, it will also include `externalGroup`.<\/p>\n

\"Code<\/p>\n

Introducing the identity resource type<\/strong><\/p>\n

Along with simplifying the acl<\/strong> resource type, we are also simplifying the externalGroupMember<\/strong> API. We have introduced a new resource type microsoft.graph.externalConnector.identity with a simpler structure. Note that specifying the OData.type along with this API call isn’t required.<\/p>\n

\"Example<\/p>\n

authorizedApps in the externalConnection object renamed to authorizedAppIds<\/strong><\/p>\n

When creating a connection, developers can optionally supply an array of Azure Active Directory client IDs to authorize more than one application to manage the connection, and read and write its contents. No action is required if you aren\u2019t using authorizedApps<\/strong>.<\/p>\n

\"Code<\/p>\n

Support during transition<\/h4>\n

To help ease the transition, we will offer backward compatibility until September 30, 2021<\/strong>. Please update your applications to ensure continued operation.<\/p>\n

You will find the updated documentation at\u00a0https:\/\/aka.ms\/graphconnectorsapi<\/a>. If you have questions you can reach out to us on Microsoft Q&A<\/a>.<\/p>\n

Please continue to share your feedback and help us improve the platform. Happy coding!<\/p>\n","protected":false},"excerpt":{"rendered":"

We have made improvements to our API to make it more useful and intuitive to developers. Implementing these improvements requires us to introduce some breaking changes detailed here.<\/p>\n","protected":false},"author":69082,"featured_media":6844,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[21],"class_list":["post-6571","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph","tag-connectors"],"acf":[],"blog_post_summary":"

We have made improvements to our API to make it more useful and intuitive to developers. Implementing these improvements requires us to introduce some breaking changes detailed here.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/6571","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69082"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=6571"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/6571\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/6844"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=6571"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=6571"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=6571"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}