获取开放扩展Get open extension

获取用名称或完全限定的名称标识的开放扩展(openTypeExtension 对象)。Get an open extension (openTypeExtension object) identified by name or fully qualified name.

下表列出了可以从受支持的资源实例中获取开放扩展的三种应用场景。The following table lists the three scenarios where you can get an open extension from a supported resource instance.

GET 应用场景GET scenario 支持的资源Supported resources 响应正文Response body
从已知资源实例中获取特定扩展。Get a specific extension from a known resource instance. 设备事件组事件组帖子邮件组织个人联系人用户Device, event, group, group event, group post, message, organization, personal contact, user 仅开放扩展。Open extension only.
获取一个通过特定扩展插件扩展的已知资源实例。Get a known resource instance expanded with a specific extension. 设备、事件、组、组事件、组帖子、邮件、组织、个人联系人、用户Device, event, group, group event, group post, message, organization, personal contact, user 一个通过开放扩展插件扩展的资源实例。A resource instance expanded with the open extension.
查找并展开具有特定扩展的资源实例。Find and expand resource instances with a specific extension. 事件、组事件、组帖子、邮件、个人联系人Event, group event, group post, message, personal contact 通过开放扩展展开的资源实例。Resource instances expanded with the open extension.

权限Permissions

根据包含扩展的资源和所请求的权限类型(委派或应用程序),下表中指定的权限是指调用此 API 所需的最低限度的特权。Depending on the resource that contains the extension and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. 若要了解详细信息,包括如何选择权限的信息,请参阅权限To learn more, including how to choose permissions, see Permissions.

支持的资源Supported resource 委派(工作或学校帐户)Delegated (work or school account) 委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) 应用程序Application
设备device Directory.Read.AllDirectory.Read.All 不支持Not supported Device.ReadWrite.AllDevice.ReadWrite.All
eventevent Calendars.ReadCalendars.Read Calendars.ReadCalendars.Read Calendars.ReadCalendars.Read
group Group.Read.AllGroup.Read.All 不支持Not supported Group.Read.AllGroup.Read.All
组事件group event Group.Read.AllGroup.Read.All 不支持Not supported 不支持Not supported
组帖子group post Group.Read.AllGroup.Read.All 不支持Not supported Group.Read.AllGroup.Read.All
messagemessage Mail.ReadMail.Read Mail.ReadMail.Read Mail.ReadMail.Read
组织organization User.ReadUser.Read 不支持Not supported 不支持Not supported
个人联系人personal contact Contacts.ReadContacts.Read Contacts.ReadContacts.Read Contacts.ReadContacts.Read
用户user User.ReadUser.Read User.ReadUser.Read User.Read.AllUser.Read.All

HTTP 请求HTTP request

本部分列出了上述三种 GET 应用场景中每一种的语法。This section lists the syntax for each of the three GET scenarios described above.

从已知资源实例中获取特定扩展Get a specific extension in a known resource instance

使用与获取资源实例相同的 REST 请求,并使用资源实例的 extensions 导航属性标识扩展插件。Use the same REST request as getting the resource instance, and identify the extension using the extensions navigation property of that instance.

GET /devices/{Id}/extensions/{extensionId}
GET /users/{Id|userPrincipalName}/events/{Id}/extensions/{extensionId}
GET /groups/{Id}/extensions/{extensionId}
GET /groups/{Id}/events/{Id}/extensions/{extensionId}
GET /groups/{Id}/threads/{Id}/posts/{Id}/extensions/{extensionId}
GET /users/{Id|userPrincipalName}/messages/{Id}/extensions/{extensionId}
GET /organization/{Id}/extensions/{extensionId}
GET /users/{Id|userPrincipalName}/contacts/{Id}/extensions/{extensionId}
GET /users/{Id|userPrincipalName}/extensions/{extensionId}

获取一个通过匹配的扩展插件扩展的已知资源实例Get a known resource instance expanded with a matching extension

对于事件、组事件、组帖子、邮件、个人联系人资源类型,可使用与获取资源实例相同的 REST 请求,查找 id 属性与筛选器匹配的扩展插件,然后使用此扩展插件扩展这个资源实例。For the event, group event, group post, message, personal contact resource types, you can use the same REST request as getting the resource instance, look for an extension that matches a filter on its id property, and expand the instance with the extension. 该响应包括大部分资源属性。The response includes most of the resource properties.

GET /users/{Id|userPrincipalName}/events/{Id}?$expand=extensions($filter=id eq '{extensionId}')
GET /groups/{Id}/events/{Id}?$expand=extensions($filter=id eq '{extensionId}')
GET /groups/{Id}/threads/{Id}/posts/{Id}?$expand=extensions($filter=id eq '{extensionId}')
GET /users/{Id|userPrincipalName}/messages/{Id}?$expand=extensions($filter=id eq '{extensionId}')
GET /users/{Id|userPrincipalName}/contacts/{Id}?$expand=extensions($filter=id eq '{extensionId}')

对于设备、组、组织和用户资源类型,你必须也使用 $select 参数以包括 id 属性及你在资源实例中所需的任何其他属性:For the device, group, organization, and user resource types, you must also use a $select parameter to include the id property and any other properties you want from the resource instance:

GET /devices/{Id}?$expand=extensions($filter=id eq '{extensionId}')&$select=id,{property_1},{property_n}
GET /groups/{Id}?$expand=extensions($filter=id eq '{extensionId}')&$select=id,{property_1},{property_n}
GET /organization/{Id}?$expand=extensions($filter=id eq '{extensionId}')&$select=id,{property_1},{property_n}
GET /users/{Id|userPrincipalName}?$expand=extensions($filter=id eq '{extensionId}')&$select=id,{property_1},{property_n}

筛选出多个通过匹配的扩展插件扩展的资源实例Filter for resource instances expanded with a matching extension

使用与获取一组受支持的资源相同的 REST 请求,筛选出扩展插件包含匹配的 id 属性的一组实例,然后使用此扩展插件扩展这些实例。Use the same REST request as getting a collection of the supported resource, filter the collection for instances that contain an extension with a matching id property, and expand these instances with the extension.

GET /users/{Id|userPrincipalName}/events?$filter=Extensions/any(f:f/id eq '{extensionId}')&$expand=Extensions($filter=id eq '{extensionId}')
GET /groups/{Id}/events?$filter=Extensions/any(f:f/id eq '{extensionId}')&$expand=Extensions($filter=id eq '{extensionId}')
GET /groups/{Id}/threads/{Id}/posts?$filter=Extensions/any(f:f/id eq '{extensionId}')&$expand=Extensions($filter=id eq '{extensionId}')
GET /users/{Id|userPrincipalName}/messages?$filter=Extensions/any(f:f/id eq '{extensionId}')&$expand=Extensions($filter=id eq '{extensionId}')
GET /users/{Id|userPrincipalName}/contacts?$filter=Extensions/any(f:f/id eq '{extensionId}')&$expand=Extensions($filter=id eq '{extensionId}')

注意: 以上语法显示了一些标识资源实例或集合的常见方法,以便从中获取扩展。可以用来识别这些资源实例或集合的所有其他语法均支持以类似的方式从中获取开放扩展。Note: The above syntax shows some common ways to identify a resource instance or collection, in order to get an extension from it. All other syntax that allows you to identify these resource instances or collections supports getting open extensions from them in a similar way.

路径参数Path parameters

参数Parameter 类型Type 说明Description
IdId stringstring 邮件、事件、联系人等相应集合中的对象的唯一标识符的占位符。必需。不要与 openTypeExtensionid 属性混淆。Placeholder for a unique identifier for an object in the corresponding collection such as messages, events, contacts. Required. Not to be confused with the id property of an openTypeExtension.
extensionIdextensionId stringstring 扩展名称(即扩展的唯一文本标识符)或完全限定的名称(连接扩展类型和唯一文本标识符)的占位符。创建扩展时,在 id 属性中返回完全限定的名称。必需。Placeholder for an extension name which is a unique text identifier for an extension, or a fully qualified name which concatenates the extension type and unique text identifier. The fully qualified name is returned in the id property when you create the extension. Required.

可选的查询参数Optional query parameters

请确保对 $filter 字符串中的空格字符应用 URL 编码Make sure you apply URL encoding to the space characters in the $filter string.

NameName Value 说明Description
$filter$filter stringstring 返回其 idextensionId 参数值匹配的扩展。Returns an extension with its id matching the extensionId parameter value.
具有 any 运算符的 $filter$filter with any operator stringstring 返回特定资源集合的实例,其中包含其 idextensionId 参数值匹配的扩展。Returns instances of a resource collection that contain an extension with its id matching the extensionId parameter value.
$expand$expand stringstring 展开资源实例以包含扩展。Expands a resource instance to include an extension.

请求标头Request headers

名称Name Value
AuthorizationAuthorization Bearer {token}。必需。Bearer {token}. Required.

请求正文Request body

请勿提供此方法的请求正文。Do not supply a request body for this method.

响应Response

如果成功,此方法在响应正文中返回 200 OK 响应代码和 openTypeExtension 对象。根据 GET 查询,准确的响应正文有所不同。If successful, this method returns a 200 OK response code and openTypeExtension object in the response body. Depending on the GET query, the exact response body differs.

示例Example

请求 1Request 1

第一个示例展示引用扩展的两种方式并获取指定邮件中的扩展。无论用于引用扩展的方式为何,该响应都相同。The first example shows 2 ways of referencing an extension and gets the extension in the specified message. The response is the same regardless of the way used to reference the extension.

首先,通过它的名称:First, by its name:

GET https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions/Com.Contoso.Referral

其次,通过其 ID(完全限定的名称):Second, by its ID (fully qualified name):

GET https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions/Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral

响应 1Response 1

下面是第一个示例的响应。Here is the response for the first example.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "extensionName": "Com.Contoso.Referral",
    "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "companyName": "Wingtip Toys",
    "dealValue": 500050,
    "expirationDate": "2015-12-03T10:00:00Z"
}

请求 2Request 2

第二个实例通过其名称引用扩展并获取指定组事件中的扩展。The second example references an extension by its name and gets the extension in the specified group event.

GET https://graph.microsoft.com/v1.0/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions/Com.Contoso.Deal/

响应 2Response 2

下面是第二个示例的响应。Here is the response from the second example.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups('f5480dfd-7d77-4d0b-ba2e-3391953cc74a')/events('AAMkADVl7IsAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Deal",
    "extensionName": "Com.Contoso.Deal",
    "companyName": "Alpine Skis",
    "dealValue": 1010100,
    "expirationDate": "2015-07-03T13:04:00Z"
}

请求 3Request 3

第三个示例通过包括筛选器返回的扩展获取并展开指定的邮件。此筛选器返回其 id 与完全限定的名称匹配的扩展。The third example gets and expands the specified message by including the extension returned from a filter. The filter returns the extension that has its id matching a fully qualified name.

GET https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===?$expand=extensions($filter=id%20eq%20'Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

响应 3Response 3

下面是第三个示例的响应。注意:为了简单起见,可能会将此处所示的响应对象截断。将从实际调用中返回所有属性。And here is the response from the third example. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages/$entity",
    "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
    "id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
    "changeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
    "categories": [
    ],
    "createDateTime": "2015-06-19T02:03:31Z",
    "lastModifiedDateTime": "2015-08-13T02:28:00Z",
    "subject": "Attached is the requested info",
    "bodyPreview": "See the images attached.",
    "body": {
        "contentType": "HTML",
        "content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "importance": "Normal",
    "hasAttachments": true,
    "parentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
    "from": {
        "emailAddress": {
            "address": "desmond@contoso.com",
            "name": "Desmond Raley"
        }
    },
    "sender": {
        "emailAddress": {
            "address": "desmond@contoso.com",
            "name": "Desmond Raley"
        }
    },
    "toRecipients": [
        {
            "emailAddress": {
                "address": "wendy@contoso.com",
                "name": "Wendy Molina"
            }
        }
    ],
    "ccRecipients": [
    ],
    "bccRecipients": [
    ],
    "replyTo": [
    ],
    "conversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
    "receivedDateTime": "2015-06-19T02:05:04Z",
    "sentDateTime": "2015-06-19T02:04:59Z",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isDraft": false,
    "isRead": true,
    "webLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "inferenceClassification": "Focused",
    "extensions@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('desmond40contoso.com')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions", 
    "extensions": [ 
      { 
        "@odata.type": "#microsoft.graph.openTypeExtension",
        "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
        "extensionName": "Com.Contoso.Referral",
        "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
        "companyName": "Wingtip Toys",
        "dealValue": 500050,
        "expirationDate": "2015-12-03T10:00:00Z"
      }
     ]
}

请求 4Request 4

第四个示例通过其完全限定的名称引用扩展并获取指定组帖子中的扩展。The fourth example references an extension by its fully qualified name and gets the extension in the specified group post.

GET https://graph.microsoft.com/v1.0/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAADDEd7UAAA=/extensions/Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Estimate

响应 4Response 4

下面是第四个示例的响应。Here is the response from the fourth example.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/threads('AAQkADJizZJpEWwqDHsEpV_KA%3D%3D')/posts('AAMkADJiUg96QZUkA-ICwMubAADDEd7UAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Estimate",
    "extensionName": "Com.Contoso.Estimate",
    "companyName": "Contoso",
    "expirationDate": "2015-07-03T13:04:00Z",
    "Strings@odata.type": "#Collection(String)",
    "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
    ]
}

响应 5Request 5

第五个示例查看已登录用户的邮箱中的所有邮件,并查找包含与筛选器匹配的扩展的邮件,然后通过包括扩展将其展开。此筛选器将返回其 id 属性与扩展名 Com.Contoso.Referral 匹配的扩展。The fifth example looks at all messages in the signed-in user's mailbox to find those that contain an extension matching a filter, and expands them by including the extension. The filter returns extensions that has the id property matching the extension name Com.Contoso.Referral.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=Extensions/any(f:f/id%20eq%20'Com.Contoso.Referral')&$expand=Extensions($filter=id%20eq%20'Com.Contoso.Referral')

响应 5Response 5

在第五个示例的响应中,用户邮箱中仅有一封邮件,其 id 等于 Com.Contoso.ReferralIn this response for the fifth example, there is only one message in the user's mailbox that has an extension with its id equal to Com.Contoso.Referral.

注意:为了简单起见,可能会将此处所示的响应对象截断。将从实际调用中返回所有属性。Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages",
  "value": [
  {

    "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
    "id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
    "changeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
    "categories": [
    ],
    "createDateTime": "2015-06-19T02:03:31Z",
    "lastModifiedDateTime": "2015-08-13T02:28:00Z",
    "subject": "Attached is the requested info",
    "bodyPreview": "See the images attached.",
    "body": {
        "contentType": "HTML",
        "content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "importance": "Normal",
    "hasAttachments": true,
    "parentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
    "from": {
        "emailAddress": {
            "address": "desmond@contoso.com",
            "name": "Desmond Raley"
        }
    },
    "sender": {
        "emailAddress": {
            "address": "desmond@contoso.com",
            "name": "Desmond Raley"
        }
    },
    "toRecipients": [
        {
            "emailAddress": {
                "address": "wendy@contoso.com",
                "name": "Wendy Molina"
            }
        }
    ],
    "ccRecipients": [
    ],
    "bccRecipients": [
    ],
    "replyTo": [
    ],
    "conversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
    "receivedDateTime": "2015-06-19T02:05:04Z",
    "sentDateTime": "2015-06-19T02:04:59Z",
    "isDeliveryReceiptRequested": false,
    "isReadReceiptRequested": false,
    "isDraft": false,
    "isRead": true,
    "webLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "inferenceClassification": "Focused",
    "extensions@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('desmond40contoso.com')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions", 
    "extensions": [ 
      { 
        "@odata.type": "#microsoft.graph.openTypeExtension",
        "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
        "extensionName": "Com.Contoso.Referral",
        "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
        "companyName": "Wingtip Toys",
        "dealValue": 500050,
        "expirationDate": "2015-12-03T10:00:00Z"
      }
     ]
  }
  ]
}