APIs de suplemento do Outlook

Antes que o suplemento do Outlook possa ler dados de mensagens, atualizar itens ou chamar serviços externos, ele precisa de uma referência à biblioteca Office.js, um conjunto de requisitos declarado e as permissões corretas. Este artigo explica como configurar cada um desses blocos de construção e como acessar a API do Outlook por meio do objeto Mailbox .

Biblioteca Office.js

Para interagir com a API de suplemento do Outlook, você precisa usar as APIs JavaScript no Office.js. A CDN (rede de distribuição de conteúdo) da biblioteca é https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. Os suplementos enviados ao Microsoft Marketplace devem fazer referência a Office.js por esta CDN; Eles não podem usar uma referência local.

Referência CDN em um <script> marca na <head> marca da página da web (arquivo. HTML,. aspx ou. PHP) implementa interface do usuário do seu suplemento.

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>

À medida que adicionamos novas APIs, a URL para Office.js permanecerá a mesma. Alteraremos a versão na URL somente se interrompermos um comportamento de API existente.

Importante

Ao desenvolver um suplemento para qualquer aplicativo cliente do Office, faça referência à <head> API JavaScript do Office de dentro da seção da página. Isso garante que a API seja totalmente inicializada antes de qualquer elemento de corpo.

Conjuntos de requisitos

Todas as APIs do Outlook pertencem ao conjunto de requisitos de Caixa de Correio. O conjunto de requisitos Mailbox tem versões, e cada novo conjunto de APIs lançado pertence a uma versão superior. Nem todos os clientes do Outlook darão suporte ao conjunto mais recente de APIs quando forem lançados, mas se um cliente do Outlook declarar suporte para um conjunto de requisitos, ele dará suporte a todas as APIs nesse conjunto de requisitos.

Especifique uma versão mínima de conjunto de requisitos no manifesto para controlar em quais clientes do Outlook o suplemento aparecerá. Por exemplo, se você especificar a versão 1.3 do conjunto de requisitos, o suplemento não aparecerá em nenhum cliente Outlook que não dê suporte a uma versão mínima 1.3.

A especificação de um conjunto de requisitos não limita seu suplemento às APIs nessa versão. Se o suplemento especificar a versão 1.1 do conjunto de requisitos, mas estiver sendo executado em um cliente do Outlook que dá suporte à versão 1.3, ele poderá usar as APIs v1.3. O conjunto de requisitos controla somente quais clientes do Outlook exibirão o suplemento.

Para marcar a disponibilidade de todas as APIs de um conjunto de requisitos maior do que o especificado no manifesto, você pode usar o JavaScript padrão. Por exemplo, o código a seguir verifica getItemIdAsync, o que requer o requisito de Caixa de Correio definido 1.8, antes de chamá-lo.

// Check whether a Mailbox 1.8 API is available before calling it.
if (Office.context.mailbox.item.getItemIdAsync) {
    Office.context.mailbox.item.getItemIdAsync((result) => {
        if (result.status === Office.AsyncResultStatus.Succeeded) {
            console.log("Item ID:", result.value);
        }
    });
}

Observação

essas verificações não são necessárias para APIs que estão na versão do conjunto de requisitos especificada no manifesto.

Especifique o conjunto de requisitos mínimo que proporciona suporte ao conjunto essencial de APIs para seu cenário, sem o qual os recursos do suplemento não funcionam. Você especifica o requisito definido no manifesto. A marcação varia dependendo do manifesto que você está usando.

  • Manifesto somente do suplemento: use o <Requirements> elemento. Observe que o <Methods> elemento filho of <Requirements> não é suportado nos complementos do Outlook, portanto, você não pode declarar suporte para métodos específicos.
  • Manifesto unificado do Microsoft 365: use a "extensions.capabilities" propriedade.

Para obter mais informações, consulte Manifestos de suplemento do Office e Noções básicas sobre os conjuntos de requisitos da API do Outlook.

Permissões

Seu suplemento requer as permissões apropriadas para usar as APIs de que precisa. Em geral, você deve especificar a permissão mínima necessária para o seu suplemento.

Há quatro níveis de permissões: restrita, item de leitura, item de leitura/gravação e caixa de correio de leitura/gravação. Para obter mais detalhes, confira Noções básicas sobre suplementos do Outlook.

Objeto Mailbox

Os suplementos do Outlook usam principalmente um subconjunto da API exposta no objeto Mailbox. Para acessar os objetos e membros para uso nos suplementos do Outlook, como o objeto Item no modo de redação ou leitura, use a propriedade mailbox do objeto Context para acessar o objeto Mailbox . O código a seguir é um exemplo.

// Access the Item object.
const item = Office.context.mailbox.item;

Importante

Ao chamar Office.context.mailbox.item uma mensagem, observe que o Painel de Leitura no cliente Outlook deve estar ativado. Para obter orientações sobre como configurar o Painel de Leitura, confira Usar e configurar o Painel de Leitura para visualizar mensagens.

Além disso, os suplementos do Outlook podem usar os objetos a seguir.

  • Objeto Office: para inicialização.

  • Objeto Context: para acesso a propriedades de conteúdo e idioma de exibição.

Para obter informações sobre como usar JavaScript em suplementos do Outlook, consulte Suplementos do Outlook. Para explorar a API JavaScript do Outlook, consulte a página de referência da API do Outlook .

Confira também

  • Last updated on