Suplementos do Office com o manifesto unificado do aplicativo para o Microsoft 365

  • Artigo

Este artigo apresenta o manifesto unificado do aplicativo para o Microsoft 365. Ele pressupõe que você esteja familiarizado com o manifesto de Suplementos do Office.

Dica

A Microsoft está fazendo várias melhorias na plataforma de desenvolvedor do Microsoft 365. Essas melhorias fornecem mais consistência no desenvolvimento, implantação, instalação e administração de todos os tipos de extensões do Microsoft 365, incluindo os suplementos do Office. Essas alterações são compatíveis com os suplementos existentes.

Uma melhoria importante é a capacidade de criar uma única unidade de distribuição para todas as extensões do Microsoft 365 usando o mesmo formato e esquema de manifesto.

Demos um primeiro passo importante para essas metas, tornando possível criar suplementos do Outlook com um manifesto unificado para o Microsoft 365.

Observação

  • O manifesto unificado atualmente só dá suporte a suplementos do Outlook e somente no Office vinculados a uma assinatura do Microsoft 365 e instalados no Windows, em um dispositivo móvel ou em Outlook na Web. Estamos trabalhando para estender o suporte para Excel, PowerPoint e Word, bem como para o Outlook no Mac e para versões perpétuas do Office.
  • O manifesto unificado requer a Versão 2304 do Office (Build 16320.00000) ou posterior.

Dica

Pronto para começar a usar o manifesto unificado? Comece com Criar um suplemento do Outlook com o manifesto unificado do Microsoft 365.

Principais propriedades do manifesto unificado

A documentação de referência main para a versão do manifesto unificado do aplicativo está no esquema Manifest. Esse artigo fornece informações sobre as propriedades críticas do manifesto base, mas pode não incluir nenhuma documentação da propriedade "extensões", que é a propriedade em que os Suplementos do Office estão configurados no manifesto unificado. Portanto, neste artigo, fornecemos uma breve descrição do significado das propriedades base quando o Aplicativo teams é (ou inclui) um suplemento do Office. Isso é seguido por alguma documentação básica para a propriedade "extensões" e suas propriedades descendentes. Há um manifesto de exemplo completo para um suplemento em Exemplo de manifesto unificado.

Propriedades base

Cada uma das propriedades base listadas na tabela a seguir tem uma documentação mais extensa no esquema Manifest. As propriedades base não incluídas nesta tabela não têm significado para suplementos do Office.

Propriedade JSON Objetivo
"$schema" Identifica o esquema do manifesto.
"manifestVersion" Versão do esquema do manifesto.
"id" GUID do aplicativo/suplemento do Teams.
"versão" Versão do aplicativo/suplemento do Teams. O formato deve ser n.n.n onde cada n um pode ter no máximo cinco dígitos.
"nome" Nomes curtos e longos públicos do aplicativo/suplemento do Teams. O nome curto aparece na parte superior do painel de tarefas de um suplemento.
"descrição" Descrições curtas e longas públicas do aplicativo/suplemento do Teams.
"developer" Informações sobre o desenvolvedor do aplicativo/suplemento do Teams.
"localizationInfo" Configura a localidade padrão e outras localidades com suporte.
"validDomains" Consulte Especificar domínios seguros.
"webApplicationInfo" Identifica o aplicativo Web do aplicativo/suplemento do Teams como ele é conhecido no Azure Active Directory.
"autorização" Identifica todas as permissões do Microsoft Graph que o suplemento precisa.

Propriedade "extensões"

Estamos trabalhando duro para concluir a documentação de referência para a propriedade "extensões" e suas propriedades descendentes. Enquanto isso, o seguinte fornece algumas documentações básicas. A maioria, mas não todas, das propriedades tem um elemento equivalente (ou atributo) no manifesto XML para suplementos. Na maioria das vezes, a descrição e as restrições que se aplicam ao elemento ou atributo XML também se aplicam à sua propriedade JSON equivalente no manifesto unificado. As tabelas na seção "extensões" da seção Comparar o manifesto XML com o manifesto unificado do Microsoft 365 podem ajudá-lo a determinar o equivalente XML de uma propriedade JSON.

Propriedade JSON Objetivo
"requirements.capabilities" Identifica os conjuntos de requisitos que o suplemento precisa ser instalado.
"requirements.scopes" Identifica os aplicativos do Office nos quais o suplemento pode ser instalado. Por exemplo, "email" significa que o suplemento pode ser instalado no Outlook.
"faixas de opções" As faixas de opções que o suplemento personaliza.
"ribbons.contexts" Especifica as superfícies de comando que o suplemento personaliza. Por exemplo, "mailRead" ou "mailCompose".
"ribbons.tabs" Configura guias personalizadas da faixa de opções.
"suplentes" Especifica a compatibilidade de versões anteriores com um suplemento COM equivalente, XLL ou ambos. Também especifica os ícones main que são usados para representar o suplemento em versões mais antigas do Office.
"runtimes" Configura os runtimes inseridos que o suplemento usa, incluindo vários tipos de suplementos que têm pouca ou nenhuma interface do usuário, como suplementos e comandos de função personalizados somente função.
"autoRunEvents" Remove um manipulador de eventos de um evento especificado.

Especificar domínios seguros

Há uma matriz "validDomains" no arquivo de manifesto que é usada para informar ao Office quais domínios seu suplemento deve ter permissão para navegar. Conforme observado em Especificar domínios que você deseja abrir na janela de suplemento, ao executar em Office na Web, o painel de tarefas pode ser navegado para qualquer URL. No entanto, em plataformas de área de trabalho, se o suplemento tentar ir para uma URL em um domínio diferente do domínio que hospeda a página inicial, essa URL será aberta em uma nova janela do navegador fora do painel de suplemento do aplicativo do Office.

Para substituir esse comportamento em plataformas de área de trabalho, adicione cada domínio que você deseja abrir na janela de suplemento à lista de domínios especificados na matriz "validDomains". Se o suplemento tentar ir para uma URL em um domínio que está na lista, ela então abre no painel de tarefas do Office para desktop e no Office Online. Se ele tentar ir para uma URL que não está na lista, em seguida, no Office na área de trabalho, essa URL será aberta em uma nova janela do navegador (fora do painel de tarefas de suplemento).

Exemplo de manifesto unificado

A seguir está um exemplo de um manifesto de aplicativo unificado para um suplemento.

{
  "$schema": "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/op/extensions/MicrosoftTeams.schema.json",
  "id": "00000000-0000-0000-0000-000000000000",
  "version": "1.0.0",
  "manifestVersion": "devPreview",
  "name": {
    "short": "Name of your app (<=30 chars)",
    "full": "Full name of app, if longer than 30 characters (<=100 chars)"
  },
  "description": {
    "short": "Short description of your app (<= 80 chars)",
    "full": "Full description of your app (<= 4000 chars)"
  },
  "icons": {
    "outline": "outline.png",
    "color": "color.png"
  },
  "accentColor": "#230201",
  "developer": {
    "name": "Contoso",
    "websiteUrl": "https://www.contoso.com",
    "privacyUrl": "https://www.contoso.com/privacy",
    "termsOfUseUrl": "https://www.contoso.com/servicesagreement"
  },
  "localizationInfo": {
    "defaultLanguageTag": "en-us",
    "additionalLanguages": [
      {
        "languageTag": "es-es",
        "file": "es-es.json"
      }
    ]
  },
  "webApplicationInfo": {
    "id": "00000000-0000-0000-0000-000000000000",
    "resource": "api://www.contoso.com/prodapp"
  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        {
          "name": "Mailbox.ReadWrite.User",
          "type": "Delegated"
        }
      ]
    }
  },
  "extensions": [
    {
      "requirements": {
        "scopes": [ "mail" ],
        "capabilities": [
          {
            "name": "Mailbox", "minVersion": "1.1"
          }
        ]
      },
      "runtimes": [
        {
          "requirements": {
            "capabilities": [
              {
                "name": "MailBox", "minVersion": "1.10"
              }
            ]
          },
          "id": "eventsRuntime",
          "type": "general",
          "code": {
            "page": "https://contoso.com/events.html",
            "script": "https://contoso.com/events.js"
          },
          "lifetime": "short",
          "actions": [
            {
              "id": "onMessageSending",
              "type": "executeFunction"
            },
            {
              "id": "onNewMessageComposeCreated",
              "type": "executeFunction"
            }
          ]
        },
        {
          "requirements": {
            "capabilities": [
              {
                "name": "MailBox", "minVersion": "1.1"
              }
            ]
          },
          "id": "commandsRuntime",
          "type": "general",
          "code": {
            "page": "https://contoso.com/commands.html",
            "script": "https://contoso.com/commands.js"
          },
          "lifetime": "short",
          "actions": [
            {
              "id": "action1",
              "type": "executeFunction"
            },
            {
              "id": "action2",
              "type": "executeFunction"
            },
            {
              "id": "action3",
              "type": "executeFunction"
            }
          ]
        }
      ],
      "ribbons": [
        {
          "contexts": [
            "mailCompose"
          ],
          "tabs": [
            {
              "builtInTabId": "TabDefault",
              "groups": [
                {
                  "id": "dashboard",
                  "label": "Controls",
                  "controls": [
                    {
                      "id": "control1",
                      "type": "button",
                      "label": "Action 1",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "Action 1 Title",
                        "description": "Action 1 Description"
                      },
                      "actionId": "action1"
                    },
                    {
                      "id": "menu1",
                      "type": "menu",
                      "label": "My Menu",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "My Menu",
                        "description": "Menu with 2 actions"
                      },
                      "items": [
                        {
                          "id": "menuItem1",
                          "type": "menuItem",
                          "label": "Action 2",
                          "supertip": {
                            "title": "Action 2 Title",
                            "description": "Action 2 Description"
                          },
                          "actionId": "action2"
                        },
                        {
                          "id": "menuItem2",
                          "type": "menuItem",
                          "label": "Action 3",
                          "icons": [
                            {
                              "size": 16,
                              "url": "test_16.png"
                            },
                            {
                              "size": 32,
                              "url": "test_32.png"
                            },
                            {
                              "size": 80,
                              "url": "test_80.png"
                            }
                          ],
                          "supertip": {
                            "title": "Action 3 Title",
                            "description": "Action 3 Description"
                          },
                          "actionId": "action3"
                        }
                      ]
                    }
                  ]
                }
              ],
            }
          ]
        },
        {
          "contexts": [ "mailRead" ],
          "tabs": [
            {
              "builtInTabId": "TabDefault",
              "groups": [
                {
                  "id": "dashboard",
                  "label": "Controls",
                  "controls": [
                    {
                      "id": "control1",
                      "type": "button",
                      "label": "Action 1",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "Action 1 Title",
                        "description": "Action 1 Description"
                      },
                      "actionId": "action1"
                    }
                  ]
                }
              ],
              "customMobileRibbonGroups" [
                {
                  "id": "myMobileGroup",
                  "label": "Contoso Actions",
                  "controls": [
                    {
                      "id": "msgReadFunctionButton",
                      "type": "MobileButton",
                      "label": "Action 1",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "Action 1 Title",
                        "description": "Action 1 Description"
                      },
                      "actionId": "action1"
                    }
                  ]
                }
              ]
              "customMobileRibbonGroups": [
                {
                  "id": "mobileDashboard",
                  "label": "Controls",
                  "controls": [
                    {
                      "id": "control1",
                      "type": "MobileButton",
                      "label": "Action 1",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "Action 1 Title",
                        "description": "Action 1 Description"
                      },
                      "actionId": "action1"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "autoRunEvents": [
        {
          "requirements": {
            "capabilities": [
              {
                "name": "MailBox", "minVersion": "1.10"
              }
            ]
          },
          "events": [
            {
              "type": "newMessageComposeCreated",
              "actionId": "onNewMessageComposeCreated"
            },
            {
              "type": "messageSending",
              "actionId": "onMessageSending",
              "options": {
                "sendMode": "promptUser"
              }
            }
          ]
        }
      ],
      "alternates": [
        {
          "requirements": {
            "scopes": [ "mail" ]
          },
          "prefer": {
            "comAddin": {
              "progId": "ContosoExtension"
            }
          },
          "hide": {
            "storeOfficeAddin": {
              "officeAddinId": "00000000-0000-0000-0000-000000000000",
              "assetId": "WA000000000"
            }
          },
          "alternateIcons": {
            "icon": {
              "size": 64,
              "url": "https://contoso.com/assets/icon64x64.jpg"
            },
            "highResolutionIcon": {
              "size": 64,
              "url": "https://contoso.com/assets/icon128x128.jpg"
            }
          }
          "alternateIcons": {
            "icon": {
              "size": 16,
              "url": "https://cdn.contoso.com/resources/icon64.jpg"
            },
            "highResolutionIcon": {
              "size": 16,
              "url": "https://cdn.contoso.com/resources/icon128.jpg"
            },
          }
        }
      ]
    }
  ]
}

Confira também