如何：手动注册文件处理程序外接程序

2023-04-08

若要开发文件处理程序外接程序，必须先将文件处理程序清单上传到 Azure Active Directory 的“应用注册”中。这可以通过编程方式或通过 Azure Active Directory 应用清单编辑器完成。

应用清单和 addIns 属性

文件处理程序清单与应用清单一起存储在 Azure Active Directory 中。应用清单的 addIns 属性列出了应用的外接程序组件，如文件处理程序及其相关属性。

文件处理程序清单由一组定义文件处理程序属性的键值属性构成。有关文件处理程序清单的详细信息，请参阅文件处理程序概述。

示例文件处理程序清单：

{
"id": "968A844F-7A47-430C-9163-07AE7C31D407",
"type": "FileHandler",
"properties": [
    { "key": "version", "value": "2" },
    { "key": "fileTypeDisplayName", "value": "Display name of the file format" },
    { "key": "fileTypeIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
    { "key": "appIcon", "value": "{\"svg\":\"https://example.org/app-icon.svg\",\"png1x\":\"https://example.org/app-icon@1x.png\",\"png1.5x\":\"https://example.org/app-icon@1.5x.png\",\"png2x\":\"https://example.org/app-icon@2x.png\"}" },
    { "key": "actions", "value": "json string of additional actions"}
  ]
}

若要注册文件处理程序，必须在 Azure Active Directory 中存储的应用清单内更新 addIns 集合。

更新 AAD 中的应用清单

此方法要求直接在 AAD 中更新 JSON 清单。

导航到 Azure Active Directory 中的应用程序
选择“清单”左侧菜单选项
将文件处理程序Add-In JSON 粘贴到“addIns”数组中，如下所示：

{
	"id": "9280aaa1-65c3-4a01-9ced-4f3e8e989c56",
	"acceptMappedClaims": null,
	"accessTokenAcceptedVersion": 2,
	"addIns": [
		{
			"id": "328486ea-7159-4b6a-a2aa-f036b2423b23",
			"type": "FileHandler",
			"properties": [
				{
					"key": "version",
					"value": "2"
				},
				{
					"key": "fileTypeDisplayName",
					"value": "Contoso Markdown"
				},
				{
					"key": "fileTypeIcon",
					"value": "{\"svg\":\"https://localhost:3000/images/icons/icon.svg\",\"png1x\":\"https://localhost:3000/images/icons/icon@1x.png\",\"png1.5x\":\"https://localhost:3000/images/icons/icon@1.5x.png\",\"png2x\":\"https://localhost:3000/images/icons/icon@2x.png\"}"
				},
				{
					"key": "appIcon",
					"value": "{\"svg\":\"https://localhost:3000/images/icons/app-icon.svg\",\"png1x\":\"https://localhost:3000/images/icons/app-icon@1x.png\",\"png1.5x\":\"https://localhost:3000/images/icons/app-icon@1.5x.png\",\"png2x\":\"https://localhost:3000/images/icons/app-icon@2x.png\"}"
				},
				{
					"key": "actions",
					"value": "[{\"type\":\"newFile\",\"url\":\"https://localhost:3000/markdown/create\",\"availableOn\":{\"file\":{\"extensions\":[\".md\"]},\"web\":{}}},{\"type\":\"open\",\"url\":\"https://localhost:3000/markdown/edit\",\"availableOn\":{\"file\":{\"extensions\":[\".md\"]},\"web\":{}}},{\"type\":\"preview\",\"url\":\"https://localhost:3000/markdown/preview\",\"availableOn\":{\"file\":{\"extensions\":[\".md\"]},\"web\":{}}}]"
				}
			]
		}
	],
  "allowPublicClient": true,
  remainder omitted...
}

从顶部菜单栏中选择“保存”

使用 Microsoft Graph 注册文件处理程序

可以编程方式更新 AAD 应用程序注册以添加文件处理程序清单。这需要两个现有应用程序 - 文件处理程序应用程序和一个有权 Directory.ReadWrite.All 允许更新文件处理程序注册的应用程序。

需要获取持有者令牌才能访问 Microsoft Graph。若要详细了解令牌，请参阅 AAD 令牌文档。此令牌必须包含 Directory.ReadWrite.All 上述权限。
请注意应用程序 的对象 ID ，它表示清单将注入到其中的文件处理程序注册。这可以在应用程序注册的“概述”页上找到，它不同于应用程序 ID。
现在，使用步骤 1 中的令牌和步骤 2 中的对象 ID，可以发出 PUT 请求，以 https://graph.microsoft.com/v1.0/applications/${objectId}/addIns 将清单包含在正文中，如下所示。

PUT https://graph.microsoft.com/v1.0/applications/${objectId}/addIns HTTP/1.1
Authorization: Bearer ${AAD Token}
Accept: application/json
Content-Type: application/json

{
  "value": [{
      {
        "id": "968A844F-7A47-430C-9163-07AE7C31D407",
        "type": "FileHandler",
        "properties": [
            { "key": "version", "value": "2" },
            { "key": "fileTypeDisplayName", "value": "Display name of the file format" },
            { "key": "fileTypeIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
            { "key": "appIcon", "value": "{\"svg\":\"https://example.org/app-icon.svg\",\"png1x\":\"https://example.org/app-icon@1x.png\",\"png1.5x\":\"https://example.org/app-icon@1.5x.png\",\"png2x\":\"https://example.org/app-icon@2x.png\"}" },
            { "key": "actions", "value": "json string of additional actions"}
        ]
        }
  }]
}

至此，已在 AAD 中向应用注册文件处理程序清单，可以继续生成并测试文件处理程序外接程序了。

注意

可以在 Nodejs 示例的工具中看到获取令牌、创建应用程序以及注册文件处理程序加载项的完整示例。

重要

对文件处理程序清单的更改可能需要 24-48 小时才能显示。请参阅刷新文件处理程序缓存，了解如何出于开发目的强制清除缓存。

通过

如何：手动注册文件处理程序外接程序

应用清单和 addIns 属性

更新 AAD 中的应用清单

使用 Microsoft Graph 注册文件处理程序

其他资源