Как зарегистрировать надстройку-обработчик файлов вручную

  • Статья

Чтобы создать надстройку для обработки файлов, необходимо сначала отправить манифест обработчика файлов на портал регистрации приложений в 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"}
  ]
}

Чтобы зарегистрировать обработчик файлов, необходимо обновить коллекцию addIns в манифесте приложения, который хранится в Azure Active Directory.

Обновление манифеста приложения в AAD

Этот метод требует обновления манифеста JSON непосредственно в AAD.

  1. Перейдите к приложению в Azure Active Directory
  2. Выберите пункт меню "Манифест" слева
  3. Вставьте обработчик файлов 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...
}
  1. Выберите "Сохранить" в верхней строке меню.

Регистрация обработчика файлов с помощью Microsoft Graph

Вы можете программно обновить регистрацию приложения AAD, чтобы добавить манифест обработчика файлов. Для этого требуются два существующих приложения — приложение обработчика файлов и приложение с Directory.ReadWrite.All разрешениями на обновление регистрации обработчика файлов.

  1. Для доступа к Microsoft Graph потребуется получить маркер носителя. Дополнительные сведения о маркерах см. в документации по маркерам AAD. Этот маркер должен включать разрешения, Directory.ReadWrite.All как упоминалось выше.

  2. Обратите внимание на идентификатор объекта приложения, представляющего регистрацию обработчика файлов, в которую будет внедрен манифест. Это можно найти на странице "Обзор" регистрации приложения и отличается от идентификатора приложения.

  3. Теперь с помощью маркера из шага 1 и идентификатора объекта из шага 2 можно выполнить запрос 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 часов. Сведения о принудительной очистке кэша для разработки см. в статье Обновление кэша обработчика файлов.