Office.Mailbox interface

Referência

Pacote:: outlook

Fornece acesso ao modelo de objeto de suplemento do Microsoft Outlook.

Propriedades da chave:

diagnostics : fornece informações de diagnóstico a um suplemento do Outlook.
item : fornece métodos e propriedades para aceder a uma mensagem ou compromisso num suplemento do Outlook.
userProfile : fornece informações sobre o utilizador num suplemento do Outlook.

Comentários

Nível mínimo de permissão: restrito

Modo Outlook aplicável: Compose ou Leitura

Exemplos

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

function loadNewItem(eventArgs) {
    const item = Office.context.mailbox.item;

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

Propriedades

diagnostics	Fornece informações de diagnóstico para um suplemento do Outlook. Contém os seguintes membros. `hostName` (cadeia): uma cadeia que representa o nome da aplicação do Office. Deve ser um dos seguintes valores: `Outlook`, ,`OutlookWebAppnewOutlookWindows` , `OutlookIOS`ou .`OutlookAndroid` Nota: o valor "Outlook" é devolvido para o Outlook no Windows (clássico) e no Mac. `hostVersion`(cadeia): uma cadeia que representa a versão da aplicação do Office ou do Exchange Server (por exemplo, "15.0.468.0"). Se o suplemento de correio estiver a ser executado no Outlook no Windows (clássico), no Mac ou em dispositivos móveis, a `hostVersion` propriedade devolve a versão do cliente Outlook. No Outlook na Web e no novo Outlook no Windows, a propriedade devolve a versão do Exchange Server. `OWAView`(`MailboxEnums.OWAView` ou cadeia): uma enumeração (ou literal de cadeia) que representa a vista atual de Outlook na Web. Se a aplicação não estiver Outlook na Web, aceder a esta propriedade resultará em indefinido. Outlook na Web tem três vistas (`OneColumn` - apresentadas quando o ecrã é estreito, `TwoColumns` - apresentadas quando o ecrã é mais largo e `ThreeColumns` - apresentadas quando o ecrã é largo) que correspondem à largura do ecrã e da janela e ao número de colunas que podem ser apresentadas. Mais informações estão em Office.Diagnostics.
ewsUrl	Obtém a URL do ponto de extremidade dos Serviços Web do Exchange (EWS) para esta conta de email.
item	O item da caixa de correio. Consoante o contexto em que o suplemento foi aberto, o tipo de item pode variar. Se quiser ver o IntelliSense apenas para um tipo ou modo específico, cast este item para um dos seguintes: MessageCompose, MessageRead, AppointmentCompose, AppointmentRead Importante: Ao chamar `Office.context.mailbox.item` uma mensagem, tenha em atenção que o Painel de Leitura no cliente do Outlook tem de estar ativado. Para obter orientações sobre como configurar o Painel de Leitura, consulte Utilizar e configurar o Painel de Leitura para pré-visualizar mensagens. `item` pode ser nulo se o suplemento suportar afixar o painel de tarefas. Para obter detalhes sobre como lidar, veja Implementar um painel de tarefas afixável no Outlook.
masterCategories	Obtém um objeto que fornece métodos para gerir as categorias master lista associada a uma caixa de correio.
restUrl	Obtém a URL do ponto de extremidade de REST para esta conta de email.
userProfile	Informações sobre o utilizador associado à caixa de correio. Isto inclui o tipo de conta, o nome a apresentar, o endereço de e-mail e o fuso horário. Mais informações em Office.UserProfile

Métodos

addHandlerAsync(eventType, handler, options, callback)	Adiciona um manipulador de eventos a um evento com suporte. Nota: os eventos só estão disponíveis com a implementação do painel de tarefas. Para eventos suportados, veja a secção Eventos do modelo de objetos da Caixa de Correio.
addHandlerAsync(eventType, handler, callback)	Adiciona um manipulador de eventos a um evento com suporte. Nota: os eventos só estão disponíveis com a implementação do painel de tarefas. Para eventos suportados, veja a secção Eventos do modelo de objetos da Caixa de Correio.
convertToEwsId(id, restVersion)	Converte um ID suportado no formato Exchange Web Services (EWS).
convertToLocalClientTime(timeValue)	Obtém um dicionário contendo informações de hora em tempo local do cliente. O fuso horário utilizado pelo cliente do Outlook varia consoância com a plataforma. O Outlook no Windows (clássico) e no Mac utilizam o fuso horário do computador cliente. Outlook na Web e o novo Outlook no Windows utilizam o fuso horário definido no Exchange Administração Center (EAC). Você deve lidar com valores de data e hora para que os valores exibidos na interface do usuário sejam sempre consistentes com o fuso horário que o usuário espera. No Outlook no Windows (clássico) e no Mac, o `convertToLocalClientTime` método devolve um objeto de dicionário com os valores definidos para o fuso horário do computador cliente. No Outlook na Web e no novo Outlook no Windows, o `convertToLocalClientTime` método devolve um objeto de dicionário com os valores definidos para o fuso horário especificado no EAC.
convertToRestId(id, restVersion)	Converte um ID suportado em formato REST.
convertToUtcClientTime(input)	Obtém um `Date` objeto de um dicionário que contém informações de tempo. O `convertToUtcClientTime` método converte um dicionário que contém uma data e hora locais num `Date` objeto com os valores corretos para a data e hora locais.
displayAppointmentForm(itemId)	Exibe um compromisso de calendário existente. O `displayAppointmentForm` método abre um compromisso de calendário existente numa nova janela no ambiente de trabalho. No Outlook para Mac, pode utilizar este método para apresentar um único compromisso que não faça parte de uma série periódica ou o master compromisso de uma série periódica. No entanto, não pode apresentar uma instância da série porque não consegue aceder às propriedades (incluindo o ID do item) das instâncias de uma série periódica. No Outlook na Web e no novo Outlook no Windows, este método só abre o formulário especificado se o corpo do formulário for menor ou igual a 32 mil carateres. Se o identificador do item especificado não identificar um compromisso existente, é aberto um painel em branco no computador ou dispositivo cliente e não é devolvida nenhuma mensagem de erro.
displayMessageForm(itemId)	Exibe uma mensagem existente. O `displayMessageForm` método abre uma mensagem existente numa nova janela no ambiente de trabalho. No Outlook na Web e no novo Outlook no Windows, este método só abre o formulário especificado se o corpo do formulário for menor ou igual a 32 mil carateres. Se o identificador do item especificado não identificar uma mensagem existente, não será apresentada nenhuma mensagem no computador cliente e não será devolvida nenhuma mensagem de erro.
displayNewAppointmentForm(parameters)	Exibe um formulário para criar um compromisso no calendário. O método `displayNewAppointmentForm` abre um formulário que permite ao usuário criar um novo compromisso ou reunião. Se os parâmetros forem especificados, os campos de formulário do compromisso serão preenchidos automaticamente com o conteúdo dos parâmetros. No Outlook na Web e no novo Outlook no Windows, este método apresenta sempre um formulário com um campo de participantes. Se não especificar participantes como argumentos de entrada, o método apresenta um formulário com um botão Guardar . Se você especificar participantes, o formulário inclui os participantes e um botão Enviar. No Outlook no Windows (clássico) e no Mac, se especificar quaisquer participantes ou recursos no `requiredAttendees`parâmetro , `optionalAttendees`ou `resources` , este método apresenta um formulário de reunião com um botão Enviar . Se você não especificar destinatários, este método exibirá um formulário de compromisso com um botão Salvar e Fechar. Se qualquer dos parâmetros exceder os limites de tamanho especificados, ou se um nome de parâmetro desconhecido for especificado, ocorre uma exceção.
displayNewMessageForm(parameters)	Apresenta um formulário para criar uma nova mensagem. O `displayNewMessageForm` método abre um formulário que permite ao utilizador criar uma nova mensagem. Se forem especificados parâmetros, os campos do formulário de mensagem são preenchidos automaticamente com o conteúdo dos parâmetros. Se qualquer dos parâmetros exceder os limites de tamanho especificados, ou se um nome de parâmetro desconhecido for especificado, ocorre uma exceção.
getCallbackTokenAsync(options, callback)	Obtém uma cadeia que contém um token utilizado para chamar APIs REST ou Serviços Web exchange (EWS). O método `getCallbackTokenAsync` faz uma chamada assíncrona para obter um token opaco do Exchange Server que hospeda a caixa de correio do usuário. A vida útil do token de retorno de chamada é de 5 minutos. O token é devolvido como uma cadeia na `asyncResult.value` propriedade .
getCallbackTokenAsync(callback, userContext)	Obtém uma cadeia de caracteres que contém um token usado para obter um anexo ou um item de um Exchange Server. O método `getCallbackTokenAsync` faz uma chamada assíncrona para obter um token opaco do Exchange Server que hospeda a caixa de correio do usuário. A vida útil do token de retorno de chamada é de 5 minutos. O token é devolvido como uma cadeia na `asyncResult.value` propriedade .
getIsIdentityManaged()	Devolve true se a caixa de correio atual for gerida por Microsoft Intune.
getIsOpenFromLocationAllowed(openLocation)	Devolve verdadeiro se a política Intune gestão de aplicações móveis (MAM) de uma organização permitir que um suplemento aceda aos dados a partir da localização especificada.
getIsSaveToLocationAllowed(saveLocation)	Devolve verdadeiro se a política Intune gestão de aplicações móveis (MAM) de uma organização permitir que um suplemento guarde dados na localização especificada.
getUserIdentityTokenAsync(callback, userContext)	Obtém um símbolo que identifica o usuário e o suplemento do Office. O token é devolvido como uma cadeia na `asyncResult.value` propriedade .
makeEwsRequestAsync(data, callback, userContext)	Faz um pedido assíncrono a um serviço dos Serviços Web exchange (EWS) no servidor Exchange que aloja a caixa de correio do utilizador. O método `makeEwsRequestAsync` envia uma solicitação do EWS em nome do suplemento ao Exchange.
removeHandlerAsync(eventType, options, callback)	Remove um manipulador de eventos para um tipo de evento com suporte. Nota: os eventos só estão disponíveis com a implementação do painel de tarefas. Para eventos suportados, veja a secção Eventos do modelo de objetos da Caixa de Correio.
removeHandlerAsync(eventType, callback)	Remove um manipulador de eventos para um tipo de evento com suporte. Nota: os eventos só estão disponíveis com a implementação do painel de tarefas. Para eventos suportados, veja a secção Eventos do modelo de objetos da Caixa de Correio.

Detalhes da propriedade

diagnostics

Fornece informações de diagnóstico para um suplemento do Outlook.

Contém os seguintes membros.

hostName (cadeia): uma cadeia que representa o nome da aplicação do Office. Deve ser um dos seguintes valores: Outlook, ,OutlookWebAppnewOutlookWindows , OutlookIOSou .OutlookAndroid Nota: o valor "Outlook" é devolvido para o Outlook no Windows (clássico) e no Mac.
hostVersion(cadeia): uma cadeia que representa a versão da aplicação do Office ou do Exchange Server (por exemplo, "15.0.468.0"). Se o suplemento de correio estiver a ser executado no Outlook no Windows (clássico), no Mac ou em dispositivos móveis, a hostVersion propriedade devolve a versão do cliente Outlook. No Outlook na Web e no novo Outlook no Windows, a propriedade devolve a versão do Exchange Server.
OWAView(MailboxEnums.OWAView ou cadeia): uma enumeração (ou literal de cadeia) que representa a vista atual de Outlook na Web. Se a aplicação não estiver Outlook na Web, aceder a esta propriedade resultará em indefinido. Outlook na Web tem três vistas (OneColumn - apresentadas quando o ecrã é estreito, TwoColumns - apresentadas quando o ecrã é mais largo e ThreeColumns - apresentadas quando o ecrã é largo) que correspondem à largura do ecrã e da janela e ao número de colunas que podem ser apresentadas.

Mais informações estão em Office.Diagnostics.

diagnostics: Diagnostics;

Valor da propriedade

Office.Diagnostics

Comentários

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

A partir do conjunto de requisitos da Caixa de Correio 1.5, também pode utilizar a propriedade Office.context.diagnóstico para obter informações semelhantes.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-diagnostic-information.yaml

// This function gets a mailbox's diagnostic information, such as Outlook client and version, and logs it to the console.
const diagnostics = Office.context.mailbox.diagnostics;
console.log(`Client application: ${diagnostics.hostName}`);
console.log(`Client version: ${diagnostics.hostVersion}`);

switch (diagnostics.OWAView) {
  case undefined:
    console.log("Current view (Outlook on the web only): Not applicable. An Outlook desktop client is in use.");
    break;
  case Office.MailboxEnums.OWAView.OneColumnNarrow:
    console.log("Current view (Outlook on the web only): Viewed from an older generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.OneColumn:
    console.log("Current view (Outlook on the web only): Viewed from a newer generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.TwoColumns:
    console.log("Current view (Outlook on the web only): Viewed from a tablet");
    break;
  case Office.MailboxEnums.OWAView.ThreeColumns:
    console.log("Current view (Outlook on the web only): Viewed from a desktop computer");
    break;
}

ewsUrl

Obtém a URL do ponto de extremidade dos Serviços Web do Exchange (EWS) para esta conta de email.

ewsUrl: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

Importante:

A aplicação tem de ter a permissão ler item especificada no respetivo manifesto para chamar o ewsUrl membro no modo de leitura.
No modo de composição, tem de chamar o saveAsync método antes de poder utilizar o ewsUrl membro. A sua aplicação tem de ter permissões de item de leitura/escrita para chamar o saveAsync método .
Esta propriedade não é suportada no Outlook para Android ou iOS. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.
O valor ewsUrl pode ser usado por um serviço remoto para fazer chamadas do EWS à caixa de correio do usuário. Por exemplo, pode criar um serviço remoto para obter anexos a partir do item selecionado.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

item

O item da caixa de correio. Consoante o contexto em que o suplemento foi aberto, o tipo de item pode variar. Se quiser ver o IntelliSense apenas para um tipo ou modo específico, cast este item para um dos seguintes:

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Importante:

Ao chamar Office.context.mailbox.item uma mensagem, tenha em atenção que o Painel de Leitura no cliente do Outlook tem de estar ativado. Para obter orientações sobre como configurar o Painel de Leitura, consulte Utilizar e configurar o Painel de Leitura para pré-visualizar mensagens.
item pode ser nulo se o suplemento suportar afixar o painel de tarefas. Para obter detalhes sobre como lidar, veja Implementar um painel de tarefas afixável no Outlook.

item?: Item & ItemCompose & ItemRead & Message & MessageCompose & MessageRead & Appointment & AppointmentCompose & AppointmentRead;

Valor da propriedade

Office.Item & Office.ItemCompose & Office.ItemRead & Office.Message & Office.MessageCompose & Office.MessageRead & Office.Appointment & Office.AppointmentCompose & Office.AppointmentRead

masterCategories

Obtém um objeto que fornece métodos para gerir as categorias master lista associada a uma caixa de correio.

masterCategories: MasterCategories;

Valor da propriedade

Office.MasterCategories

Comentários

[ Conjunto de API: Caixa de Correio 1.8 ]

Nível mínimo de permissão: caixa de correio de leitura/escrita

Modo Outlook aplicável: Compose ou Leitura

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Master categories:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories in the master list.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const masterCategoriesToAdd = [
  {
    displayName: "TestCategory",
    color: Office.MailboxEnums.CategoryColor.Preset0
  }
];

Office.context.mailbox.masterCategories.addAsync(masterCategoriesToAdd, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully added categories to master list");
  } else {
    console.log("masterCategories.addAsync call failed with error: " + asyncResult.error.message);
  }
});

...

const masterCategoriesToRemove = ["TestCategory"];

Office.context.mailbox.masterCategories.removeAsync(masterCategoriesToRemove, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed categories from master list");
  } else {
    console.log("masterCategories.removeAsync call failed with error: " + asyncResult.error.message);
  }
});

restUrl

Obtém a URL do ponto de extremidade de REST para esta conta de email.

restUrl: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: Caixa de Correio 1.5 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

Importante:

Os pontos finais REST v2.0 e beta do Outlook foram preteridos. No entanto, os suplementos disponibilizados em privado e alojados no AppSource podem utilizar o serviço REST até que o suporte alargado termine para o Outlook 2019 a 14 de outubro de 2025. O tráfego destes suplementos é identificado automaticamente para isenção. Esta isenção também se aplica a novos suplementos desenvolvidos após 31 de março de 2024. Embora os suplementos possam utilizar o serviço REST até 2025, recomendamos vivamente que migre os seus suplementos para utilizar o Microsoft Graph. Para obter orientações, veja Comparar os pontos finais da API REST do Microsoft Graph e do Outlook.
O suplemento tem de ter a permissão ler item especificada no respetivo manifesto para chamar o restUrl membro no modo de leitura.
No modo de composição, é preciso chamar o método saveAsync antes de poder usar o membro restUrl. O suplemento tem de ter permissões de item de leitura/escrita para chamar o saveAsync método . No entanto, em cenários delegados ou partilhados, deve, em vez disso, utilizar a targetRestUrl propriedade do objeto SharedProperties (introduzido no requisito definido como 1.8). Para obter mais informações, consulte o artigo pastas partilhadas e caixa de correio partilhada .

Exemplos

// Get the URL of the REST endpoint.
const restUrl = Office.context.mailbox.restUrl;
console.log(`REST API URL: ${restUrl}`);

userProfile

Informações sobre o utilizador associado à caixa de correio. Isto inclui o tipo de conta, o nome a apresentar, o endereço de e-mail e o fuso horário.

Mais informações em Office.UserProfile

userProfile: UserProfile;

Valor da propriedade

Office.UserProfile

Detalhes do método

addHandlerAsync(eventType, handler, options, callback)

Adiciona um manipulador de eventos a um evento com suporte. Nota: os eventos só estão disponíveis com a implementação do painel de tarefas.

Para eventos suportados, veja a secção Eventos do modelo de objetos da Caixa de Correio.

addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parâmetros

eventType: Office.EventType | string

O evento que deve invocar o manipulador.

handler: any

A função para manipular o evento. A função deve aceitar um parâmetro exclusivo, que é um objeto literal. A type propriedade no parâmetro corresponderá ao eventType parâmetro transmitido a addHandlerAsync.

options: Office.AsyncContextOptions

Fornece uma opção para preservar dados de contexto de qualquer tipo, inalterados, para utilização numa chamada de retorno.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro do tipo Office.AsyncResult.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.5 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

Exemplos

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

function loadNewItem(eventArgs) {
    const item = Office.context.mailbox.item;

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

addHandlerAsync(eventType, handler, callback)

Adiciona um manipulador de eventos a um evento com suporte. Nota: os eventos só estão disponíveis com a implementação do painel de tarefas.

Para eventos suportados, veja a secção Eventos do modelo de objetos da Caixa de Correio.

addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parâmetros

eventType: Office.EventType | string

O evento que deve invocar o manipulador.

handler: any

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro do tipo Office.AsyncResult.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.5 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

convertToEwsId(id, restVersion)

Converte um ID suportado no formato Exchange Web Services (EWS).

convertToEwsId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Parâmetros

id: string

O ID a converter no formato EWS. Esta cadeia pode ser um ID de item formatado para as APIs REST do Outlook ou um ID de conversação obtido a partir de Office.context.mailbox.item.conversationId.

restVersion: Office.MailboxEnums.RestVersion | string

Um valor que indica a versão da API REST do Outlook usada para recuperar a ID do item.

Retornos

string

Comentários

[ Conjunto de API: Caixa de Correio 1.3 ]

Nível mínimo de permissão: restrito

Modo Outlook aplicável: Compose ou Leitura

Importante:

Em outubro de 2024, a identidade de utilizador e os tokens de chamada de retorno legados do Exchange serão desativados por predefinição para todos os inquilinos Exchange Online. Isto faz parte da Iniciativa Secure Future da Microsoft, que fornece às organizações as ferramentas necessárias para responder ao cenário de ameaças atual. Os tokens de identidade de utilizador do Exchange continuarão a funcionar para o Exchange no local. A autenticação de aplicações aninhadas é a abordagem recomendada para tokens em curso. Para obter mais informações, veja a nossa mensagem de blogue e a página FAQ.
Este método não é suportado no Outlook para Android ou iOS. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.
Os IDs de itens obtidos através de uma API REST (como o Microsoft Graph) utilizam um formato diferente do formato utilizado pelo EWS. O método convertToEwsId converte uma ID formatada como REST para o formato adequado para EWS.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToLocalClientTime(timeValue)

Obtém um dicionário contendo informações de hora em tempo local do cliente.

O fuso horário utilizado pelo cliente do Outlook varia consoância com a plataforma. O Outlook no Windows (clássico) e no Mac utilizam o fuso horário do computador cliente. Outlook na Web e o novo Outlook no Windows utilizam o fuso horário definido no Exchange Administração Center (EAC). Você deve lidar com valores de data e hora para que os valores exibidos na interface do usuário sejam sempre consistentes com o fuso horário que o usuário espera.

No Outlook no Windows (clássico) e no Mac, o convertToLocalClientTime método devolve um objeto de dicionário com os valores definidos para o fuso horário do computador cliente. No Outlook na Web e no novo Outlook no Windows, o convertToLocalClientTime método devolve um objeto de dicionário com os valores definidos para o fuso horário especificado no EAC.

convertToLocalClientTime(timeValue: Date): LocalClientTime;

Parâmetros

timeValue: Date

Um Date objeto.

Retornos

Office.LocalClientTime

Comentários

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

convertToRestId(id, restVersion)

Converte um ID suportado em formato REST.

convertToRestId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Parâmetros

id: string

O ID a converter em formato REST. Esta cadeia pode ser um ID de item formatado para o EWS que é normalmente obtido a partir de Office.context.mailbox.item.itemId, um ID de conversação obtido deOffice.context.mailbox.item.conversationId ou um ID de série obtido a partir deOffice.context.mailbox.item.seriesId .

restVersion: Office.MailboxEnums.RestVersion | string

Um valor que indica a versão da API REST do Outlook utilizada com o ID convertido.

Retornos

string

Comentários

[ Conjunto de API: Caixa de Correio 1.3 ]

Nível mínimo de permissão: restrito

Modo Outlook aplicável: Compose ou Leitura

Importante:

Este método não é suportado no Outlook para Android ou iOS. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.
Os IDs de itens obtidos através dos Serviços Web exchange (EWS) ou através da itemId propriedade utilizam um formato diferente do formato utilizado pelas APIs REST (como o Microsoft Graph). O método convertToRestId converte uma ID formatada como EWS para o formato adequado para REST.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToUtcClientTime(input)

Obtém um Date objeto de um dicionário que contém informações de tempo.

O convertToUtcClientTime método converte um dicionário que contém uma data e hora locais num Date objeto com os valores corretos para a data e hora locais.

convertToUtcClientTime(input: LocalClientTime): Date;

Parâmetros

input: Office.LocalClientTime

O valor de hora local a converter.

Retornos

Date

Um objeto Date com a hora expressa em UTC.

Comentários

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

Exemplos

// Represents 3:37 PM PDT on Monday, August 26, 2019.
const input = {
    date: 26,
    hours: 15,
    milliseconds: 2,
    minutes: 37,
    month: 7,
    seconds: 2,
    timezoneOffset: -420,
    year: 2019
};

// result should be a Date object.
const result = Office.context.mailbox.convertToUtcClientTime(input);

// Output should be "2019-08-26T22:37:02.002Z".
console.log(result.toISOString());

displayAppointmentForm(itemId)

Exibe um compromisso de calendário existente.

O displayAppointmentForm método abre um compromisso de calendário existente numa nova janela no ambiente de trabalho.

No Outlook para Mac, pode utilizar este método para apresentar um único compromisso que não faça parte de uma série periódica ou o master compromisso de uma série periódica. No entanto, não pode apresentar uma instância da série porque não consegue aceder às propriedades (incluindo o ID do item) das instâncias de uma série periódica.

No Outlook na Web e no novo Outlook no Windows, este método só abre o formulário especificado se o corpo do formulário for menor ou igual a 32 mil carateres.

Se o identificador do item especificado não identificar um compromisso existente, é aberto um painel em branco no computador ou dispositivo cliente e não é devolvida nenhuma mensagem de erro.

displayAppointmentForm(itemId: string): void;

Parâmetros

itemId: string

O identificador dos Serviços Web do Exchange (EWS) para um compromisso de calendário existente.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

Importante: este método não é suportado no Outlook para Android ou iOS. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = $("#itemId").val();
Office.context.mailbox.displayAppointmentForm(itemId);

displayMessageForm(itemId)

Exibe uma mensagem existente.

O displayMessageForm método abre uma mensagem existente numa nova janela no ambiente de trabalho.

No Outlook na Web e no novo Outlook no Windows, este método só abre o formulário especificado se o corpo do formulário for menor ou igual a 32 mil carateres.

Se o identificador do item especificado não identificar uma mensagem existente, não será apresentada nenhuma mensagem no computador cliente e não será devolvida nenhuma mensagem de erro.

displayMessageForm(itemId: string): void;

Parâmetros

itemId: string

O identificador dos Serviços Web do Exchange (EWS) para uma mensagem existente.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

Importante:

Este método não é suportado no Outlook para Android ou iOS. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.
Não utilize o displayMessageForm com um itemId que represente um compromisso. Use o método displayAppointmentForm para exibir um compromisso existente e displayNewAppointmentForm para exibir um formulário e criar um novo compromisso.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = $("#itemId").val();
Office.context.mailbox.displayMessageForm(itemId);

displayNewAppointmentForm(parameters)

Exibe um formulário para criar um compromisso no calendário.

O método displayNewAppointmentForm abre um formulário que permite ao usuário criar um novo compromisso ou reunião. Se os parâmetros forem especificados, os campos de formulário do compromisso serão preenchidos automaticamente com o conteúdo dos parâmetros.

No Outlook na Web e no novo Outlook no Windows, este método apresenta sempre um formulário com um campo de participantes. Se não especificar participantes como argumentos de entrada, o método apresenta um formulário com um botão Guardar . Se você especificar participantes, o formulário inclui os participantes e um botão Enviar.

No Outlook no Windows (clássico) e no Mac, se especificar quaisquer participantes ou recursos no requiredAttendeesparâmetro , optionalAttendeesou resources , este método apresenta um formulário de reunião com um botão Enviar . Se você não especificar destinatários, este método exibirá um formulário de compromisso com um botão Salvar e Fechar.

Se qualquer dos parâmetros exceder os limites de tamanho especificados, ou se um nome de parâmetro desconhecido for especificado, ocorre uma exceção.

displayNewAppointmentForm(parameters: AppointmentForm): void;

Parâmetros

parameters: Office.AppointmentForm

Uma AppointmentForm descrição do novo compromisso. Todas as propriedades são opcionais.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Leitura

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

Office.context.mailbox.displayNewAppointmentForm({
  requiredAttendees: ["bob@contoso.com"],
  optionalAttendees: ["sam@contoso.com"],
  start: start,
  end: end,
  location: "Home",
  subject: "meeting",
  resources: ["projector@contoso.com"],
  body: "Hello World!"
});

displayNewMessageForm(parameters)

Apresenta um formulário para criar uma nova mensagem.

O displayNewMessageForm método abre um formulário que permite ao utilizador criar uma nova mensagem. Se forem especificados parâmetros, os campos do formulário de mensagem são preenchidos automaticamente com o conteúdo dos parâmetros.

Se qualquer dos parâmetros exceder os limites de tamanho especificados, ou se um nome de parâmetro desconhecido for especificado, ocorre uma exceção.

displayNewMessageForm(parameters: any): void;

Parâmetros

parameters: any

Um dicionário que contém todos os valores a preencher para o utilizador no novo formulário. Todos os parâmetros são opcionais.

toRecipients : uma matriz de cadeias que contém os endereços de e-mail ou uma matriz que contém um objeto EmailAddressDetails para cada um dos destinatários na linha Para . A matriz está limitada a um máximo de 100 entradas.

ccRecipients : uma matriz de cadeias que contém os endereços de e-mail ou uma matriz que contém um objeto EmailAddressDetails para cada um dos destinatários na linha Cc . A matriz está limitada a um máximo de 100 entradas.

bccRecipients : uma matriz de cadeias que contém os endereços de e-mail ou uma matriz que contém um objeto EmailAddressDetails para cada um dos destinatários na linha Bcc . A matriz está limitada a um máximo de 100 entradas.

subject : uma cadeia que contém o assunto da mensagem. A cadeia de caracteres está limitada a um máximo de 255 caracteres.

htmlBody : o corpo HTML da mensagem. O conteúdo do corpo está limitado a um tamanho máximo de 32 KB.

attachments : uma matriz de objetos JSON que são anexos de ficheiros ou itens.

attachments.type : indica o tipo de anexo. Deve ser file para um anexo de arquivo ou item para um anexo de item.

attachments.name : uma cadeia que contém o nome do anexo, até 255 carateres de comprimento.

attachments.url : utilizado apenas se o tipo de anexo estiver definido como file. O URI do local para o arquivo. Importante: esta ligação tem de estar acessível publicamente, sem necessidade de autenticação por parte Exchange Online servidores. No entanto, com o Exchange no local, a ligação pode ser acessível numa rede privada, desde que não precise de autenticação adicional.

attachments.isInline : utilizado apenas se o tipo de anexo estiver definido como file. Se for verdadeiro, indica que o anexo será apresentado inline como uma imagem no corpo da mensagem e não será apresentado na lista de anexos.

attachments.itemId : utilizado apenas se o tipo de anexo estiver definido como item. O ID do item do EWS do e-mail existente que pretende anexar à nova mensagem. Isso é uma cadeia de até 100 caracteres.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.6 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Leitura

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

Office.context.mailbox.displayNewMessageForm({
  toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
  ccRecipients: ["sam@contoso.com"],
  subject: "Outlook add-ins are cool!",
  htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
  attachments: [
    {
      type: "file",
      name: "image.png",
      url: "https://i.imgur.com/9S36xvA.jpg",
      isInline: true
    }
  ]
});

getCallbackTokenAsync(options, callback)

Obtém uma cadeia que contém um token utilizado para chamar APIs REST ou Serviços Web exchange (EWS).

O método getCallbackTokenAsync faz uma chamada assíncrona para obter um token opaco do Exchange Server que hospeda a caixa de correio do usuário. A vida útil do token de retorno de chamada é de 5 minutos.

O token é devolvido como uma cadeia na asyncResult.value propriedade .

getCallbackTokenAsync(options: Office.AsyncContextOptions & { isRest?: boolean }, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parâmetros

options: Office.AsyncContextOptions & { isRest?: boolean }

Um literal de objeto que contém uma ou mais das seguintes propriedades:- isRest: determina se o token fornecido será utilizado para as APIs REST do Outlook ou para os Serviços Web exchange. O valor predefinido é false. asyncContext : quaisquer dados de estado transmitidos para o método assíncrono.

callback: (asyncResult: Office.AsyncResult<string>) => void

Quando o método for concluído, a função transmitida no parâmetro de chamada de retorno é chamada com um único parâmetro do tipo Office.AsyncResult. O token é devolvido como uma cadeia na asyncResult.value propriedade . Se ocorreu um erro, as propriedadesasyncResult.error e asyncResult.diagnostics podem fornecer informações adicionais.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.5 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

Importante:

Em outubro de 2024, a identidade de utilizador e os tokens de chamada de retorno legados do Exchange serão desativados por predefinição para todos os inquilinos Exchange Online. Isto faz parte da Iniciativa Secure Future da Microsoft, que fornece às organizações as ferramentas necessárias para responder ao cenário de ameaças atual. Os tokens de identidade de utilizador do Exchange continuarão a funcionar para o Exchange no local. A autenticação de aplicações aninhadas é a abordagem recomendada para tokens em curso. Para obter mais informações, veja a nossa mensagem de blogue e a página FAQ.
Os pontos finais REST v2.0 e beta do Outlook foram preteridos. No entanto, os suplementos disponibilizados em privado e alojados no AppSource podem utilizar o serviço REST até que o suporte alargado termine para o Outlook 2019 a 14 de outubro de 2025. O tráfego destes suplementos é identificado automaticamente para isenção. Esta isenção também se aplica a novos suplementos desenvolvidos após 31 de março de 2024. Embora os suplementos possam utilizar o serviço REST até 2025, recomendamos vivamente que migre os seus suplementos para utilizar o Microsoft Graph. Para obter orientações, veja Comparar os pontos finais da API REST do Microsoft Graph e do Outlook.
Este método não é suportado se carregar um suplemento numa caixa de correio Outlook.com ou Gmail.
Este método só é suportado no modo de leitura no Outlook para Android e no iOS. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.
As operações do EWS não são suportadas em suplementos em execução no Outlook no iOS e no Android. Um token REST é sempre devolvido nos clientes móveis do Outlook, mesmo que options.isRest esteja definido como false.
Chamar o getCallbackTokenAsync método no modo de leitura requer um nível mínimo de permissão de item de leitura.
Chamar o getCallbackTokenAsync método no modo de composição requer que tenha guardado o item. O saveAsync método requer um nível mínimo de permissão de item de leitura/escrita.
Para obter orientações sobre cenários delegados ou partilhados, consulte o artigo pastas partilhadas e caixa de correio partilhada .

Tokens REST

Quando é pedido um token REST (options.isRest = true), o token resultante não funciona para autenticar chamadas EWS. O token será limitado no âmbito ao acesso só de leitura ao item atual e aos respetivos anexos, a menos que o suplemento tenha especificado a permissão de caixa de correio de leitura/escrita no respetivo manifesto. Se a permissão de caixa de correio de leitura/escrita for especificada, o token resultante concederá acesso de leitura/escrita ao correio, calendário e contactos, incluindo a capacidade de enviar correio.

O suplemento deve usar a propriedade restUrl para determinar a URL correta a ser usada ao fazer chamadas da API REST.

Esta API funciona para os seguintes âmbitos.

Mail.ReadWrite
Mail.Send
Calendars.ReadWrite
Contacts.ReadWrite

Tokens EWS

Quando é pedido um token EWS (options.isRest = false), o token resultante não funcionará para autenticar chamadas à API REST. O token será limitado em escopo para acessar o item atual.

O suplemento deve usar a propriedade ewsUrl para determinar a URL correta a ser usada ao fazer chamadas de EWS.

Pode transmitir o token e um identificador de anexo ou identificador de item para um sistema externo. Esse sistema utiliza o token como um token de autorização de portador para chamar a operação GetAttachment dos Serviços Web Exchange (EWS) ou a operação GetItem para devolver um anexo ou item. Por exemplo, pode criar um serviço remoto para obter anexos a partir do item selecionado.

Erros:

HTTPRequestFailure : O pedido falhou. Examine o objeto de diagnóstico para o código de erro HTTP.
InternalServerError : O servidor Exchange devolveu um erro. Para saber mais, confira o objeto de diagnóstico.
NetworkError : o utilizador já não está ligado à rede. Verifique sua conexão de rede e tente novamente.

getCallbackTokenAsync(callback, userContext)

Obtém uma cadeia de caracteres que contém um token usado para obter um anexo ou um item de um Exchange Server.

O token é devolvido como uma cadeia na asyncResult.value propriedade .

getCallbackTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parâmetros

callback: (asyncResult: Office.AsyncResult<string>) => void

userContext: any

Opcional. Quaisquer dados de estado que são passados ao método assíncrono.

Retornos

void

Comentários

[ Conjunto de API: Todos suportam o modo de Leitura; A caixa de correio 1.3 introduziu o suporte do modo Compose ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

Importante:

Em outubro de 2024, a identidade de utilizador e os tokens de chamada de retorno legados do Exchange serão desativados por predefinição para todos os inquilinos Exchange Online. Isto faz parte da Iniciativa Secure Future da Microsoft, que fornece às organizações as ferramentas necessárias para responder ao cenário de ameaças atual. Os tokens de identidade de utilizador do Exchange continuarão a funcionar para o Exchange no local. A autenticação de aplicações aninhadas é a abordagem recomendada para tokens em curso. Para obter mais informações, veja a nossa mensagem de blogue e a página FAQ.
Pode transmitir o token e um identificador de anexo ou identificador de item para um sistema externo. Esse sistema utiliza o token como um token de autorização de portador para chamar a operação GetAttachment ou GetItem dos Serviços Web exchange (EWS) para devolver um anexo ou item. Por exemplo, pode criar um serviço remoto para obter anexos a partir do item selecionado.
Chamar o getCallbackTokenAsync método no modo de leitura requer um nível mínimo de permissão de item de leitura.
Chamar o getCallbackTokenAsync método no modo de composição requer que tenha guardado o item. O saveAsync método requer um nível mínimo de permissão de item de leitura/escrita.
Este método não é suportado no Outlook para Android ou iOS. As operações do EWS não são suportadas em suplementos em execução no Outlook em clientes móveis. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.
Este método não é suportado se carregar um suplemento numa caixa de correio Outlook.com ou Gmail.
Para obter orientações sobre cenários delegados ou partilhados, consulte o artigo pastas partilhadas e caixa de correio partilhada .

Erros:

HTTPRequestFailure : O pedido falhou. Examine o objeto de diagnóstico para o código de erro HTTP.
InternalServerError : O servidor Exchange devolveu um erro. Para saber mais, confira o objeto de diagnóstico.
NetworkError : o utilizador já não está ligado à rede. Verifique sua conexão de rede e tente novamente.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-callback-token.yaml

Office.context.mailbox.getCallbackTokenAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
        return;
    }

    console.log(result.value);
});

getIsIdentityManaged()

Devolve true se a caixa de correio atual for gerida por Microsoft Intune.

getIsIdentityManaged(): boolean;

Retornos

boolean

Verdadeiro se a caixa de correio atual for gerida por Microsoft Intune.

Comentários

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose, Ler

Importante: este método só é suportado no Outlook para Android e no iOS a partir da Versão 4.2443.0.To saiba mais sobre as APIs suportadas no Outlook em dispositivos móveis. Consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Erros:

MAMServiceNotAvailable : o cliente não consegue obter a política de gestão de aplicações móveis (MAM).

getIsOpenFromLocationAllowed(openLocation)

Devolve verdadeiro se a política Intune gestão de aplicações móveis (MAM) de uma organização permitir que um suplemento aceda aos dados a partir da localização especificada.

getIsOpenFromLocationAllowed(openLocation: MailboxEnums.OpenLocation): boolean;

Parâmetros

openLocation: Office.MailboxEnums.OpenLocation

A localização a partir da qual o suplemento está a tentar aceder aos dados.

Retornos

boolean

Verdadeiro se a política de MAM Intune de uma organização permitir que um suplemento aceda aos dados a partir da localização especificada.

Comentários

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose, Ler

Importante: este método só é suportado no Outlook para Android e no iOS a partir da Versão 4.2443.0. Para saber mais sobre as APIs suportadas no Outlook em dispositivos móveis, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Erros:

InvalidOpenLocationInput : o valor da localização especificada é inválido.
MAMServiceNotAvailable : O cliente não consegue obter a política de MAM.

getIsSaveToLocationAllowed(saveLocation)

Devolve verdadeiro se a política Intune gestão de aplicações móveis (MAM) de uma organização permitir que um suplemento guarde dados na localização especificada.

getIsSaveToLocationAllowed(saveLocation: MailboxEnums.SaveLocation): boolean;

Parâmetros

saveLocation: Office.MailboxEnums.SaveLocation

A localização na qual o suplemento está a tentar guardar dados.

Retornos

boolean

Verdadeiro se a política de MAM Intune de uma organização permitir que um suplemento guarde dados na localização especificada.

Comentários

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose, Ler

Erros:

InvalidSaveLocationInput : o valor da localização especificada é inválido.
MAMServiceNotAvailable : O cliente não consegue obter a política de MAM.

getUserIdentityTokenAsync(callback, userContext)

Obtém um símbolo que identifica o usuário e o suplemento do Office.

O token é devolvido como uma cadeia na asyncResult.value propriedade .

getUserIdentityTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parâmetros

callback: (asyncResult: Office.AsyncResult<string>) => void

userContext: any

Opcional. Quaisquer dados de estado que são passados ao método assíncrono.

Retornos

void

Comentários

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

Importante:

Em outubro de 2024, a identidade de utilizador e os tokens de chamada de retorno legados do Exchange serão desativados por predefinição para todos os inquilinos Exchange Online. Isto faz parte da Iniciativa Secure Future da Microsoft, que fornece às organizações as ferramentas necessárias para responder ao cenário de ameaças atual. Os tokens de identidade de utilizador do Exchange continuarão a funcionar para o Exchange no local. A autenticação de aplicações aninhadas é a abordagem recomendada para tokens em curso. Para obter mais informações, veja a nossa mensagem de blogue e a página FAQ.
O getUserIdentityTokenAsync método devolve um token que pode utilizar para identificar e autenticar o suplemento e o utilizador com um sistema externo.
Este método não é suportado se carregar um suplemento numa caixa de correio Outlook.com ou Gmail.

Erros:

HTTPRequestFailure : O pedido falhou. Examine o objeto de diagnóstico para o código de erro HTTP.
InternalServerError : O servidor Exchange devolveu um erro. Para saber mais, confira o objeto de diagnóstico.
NetworkError : o utilizador já não está ligado à rede. Verifique sua conexão de rede e tente novamente.

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-identity-token.yaml

Office.context.mailbox.getUserIdentityTokenAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`)
        return;
    }

    console.log(result.value);
});

makeEwsRequestAsync(data, callback, userContext)

Faz um pedido assíncrono a um serviço dos Serviços Web exchange (EWS) no servidor Exchange que aloja a caixa de correio do utilizador.

O método makeEwsRequestAsync envia uma solicitação do EWS em nome do suplemento ao Exchange.

makeEwsRequestAsync(data: any, callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parâmetros

data: any

A solicitação do EWS.

callback: (asyncResult: Office.AsyncResult<string>) => void

Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro, asyncResult, que é um Office.AsyncResult objeto. A resposta XML do pedido EWS é fornecida como uma cadeia na asyncResult.value propriedade . No Outlook na Web, no Windows (novo e clássico (a partir da Versão 2303, Compilação 16225.10000)) e no Mac (a partir da Versão 16.73 (23042601)), se a resposta exceder 5 MB de tamanho, é devolvida uma mensagem de erro na asyncResult.error propriedade. Em versões anteriores do Outlook no Windows (clássico) e no Mac, é devolvida uma mensagem de erro se a resposta exceder 1 MB de tamanho.

userContext: any

Opcional. Quaisquer dados de estado que são passados ao método assíncrono.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.1 ]

Nível mínimo de permissão: caixa de correio de leitura/escrita

Modo Outlook aplicável: Compose ou Leitura

Importante:

Em outubro de 2024, a identidade de utilizador e os tokens de chamada de retorno legados do Exchange serão desativados por predefinição para todos os inquilinos Exchange Online. Isto faz parte da Iniciativa Secure Future da Microsoft, que fornece às organizações as ferramentas necessárias para responder ao cenário de ameaças atual. Os tokens de identidade de utilizador do Exchange continuarão a funcionar para o Exchange no local. A autenticação de aplicações aninhadas é a abordagem recomendada para tokens em curso. Para obter mais informações, veja a nossa mensagem de blogue e a página FAQ.
Para ativar o makeEwsRequestAsync método para fazer pedidos EWS, o administrador do servidor tem de definir OAuthAuthentication como true no diretório EWS do Servidor de Acesso de Cliente .
O seu suplemento tem de ter a permissão de caixa de correio de leitura/escrita para utilizar o makeEwsRequestAsync método . Para obter informações sobre como utilizar a permissão de caixa de correio de leitura/escrita e as operações do EWS que pode chamar com o makeEwsRequestAsync método , consulte Especificar permissões para o acesso do suplemento de correio à caixa de correio do utilizador.
Se o suplemento precisar de aceder aos Itens Associados da Pasta ou o respetivo pedido XML tiver de especificar a codificação UTF-8 (\<?xml version="1.0" encoding="utf-8"?\>), tem de utilizar as APIs REST ou do Microsoft Graph para aceder à caixa de correio do utilizador.
Este método não é suportado no Outlook para Android ou iOS. Para obter mais informações sobre as APIs suportadas no Outlook Mobile, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.
Este método não é suportado quando o suplemento é carregado numa caixa de correio do Gmail.
Quando utiliza o makeEwsRequestAsync método em suplementos que são executados em versões do Outlook anteriores à Versão 15.0.4535.1004, tem de definir o valor de codificação como ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>). Para determinar a versão de um cliente do Outlook, utilize a mailbox.diagnostics.hostVersion propriedade . Não precisa de definir o valor de codificação quando o suplemento estiver em execução no Outlook na Web ou no novo Outlook no Windows. Para determinar o cliente do Outlook no qual o suplemento está em execução, utilize a mailbox.diagnostics.hostName propriedade .

Exemplos

function getSubjectRequest(id) {
    // Return a GetItem operation request for the subject of the specified item.
    const request =
        '<?xml version="1.0" encoding="utf-8"?>' +
        '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
        '               xmlns:xsd="http://www.w3.org/2001/XMLSchema"' +
        '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
        '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
        '  <soap:Header>' +
        '    <RequestServerVersion Version="Exchange2016" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
        '  </soap:Header>' +
        '  <soap:Body>' +
        '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
        '      <ItemShape>' +
        '        <t:BaseShape>IdOnly</t:BaseShape>' +
        '        <t:AdditionalProperties>' +
        '            <t:FieldURI FieldURI="item:Subject"/>' +
        '        </t:AdditionalProperties>' +
        '      </ItemShape>' +
        '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
        '    </GetItem>' +
        '  </soap:Body>' +
        '</soap:Envelope>';

    return request;
}

function sendRequest() {
    // Create a local variable that contains the mailbox.
    Office.context.mailbox.makeEwsRequestAsync(
        getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
    const result = asyncResult.value;
    const context = asyncResult.asyncContext;

    // Process the returned response here.
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/get-icaluid-as-attendee.yaml

const ewsId = Office.context.mailbox.item.itemId;
const request = `<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Header><t:RequestServerVersion Version="Exchange2013" /></soap:Header>
      <soap:Body>
        <m:GetItem>
          <m:ItemShape>
            <t:BaseShape>AllProperties</t:BaseShape>
          </m:ItemShape >
          <m:ItemIds>
            <t:ItemId Id="${ewsId}" />
          </m:ItemIds>
        </m:GetItem>
      </soap:Body>
    </soap:Envelope>`;

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(result.error.message);
    return;
  }

  console.log(getUID(result.value));
});

...

const request = '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">'+
    '  <soap:Header><t:RequestServerVersion Version="Exchange2010" /></soap:Header>'+
    '  <soap:Body>'+
    '    <m:CreateItem MessageDisposition="SendAndSaveCopy">'+
    '      <m:SavedItemFolderId><t:DistinguishedFolderId Id="sentitems" /></m:SavedItemFolderId>'+
    '      <m:Items>'+
    '        <t:Message>'+
    '          <t:Subject>Hello, Outlook!</t:Subject>'+
    '          <t:Body BodyType="HTML">This message was sent from a ScriptLab code sample, used from ' + Office.context.mailbox.diagnostics.hostName + ', version ' + Office.context.mailbox.diagnostics.hostVersion + '!</t:Body>'+
    '          <t:ToRecipients>'+
    '            <t:Mailbox><t:EmailAddress>' + Office.context.mailbox.userProfile.emailAddress + '</t:EmailAddress></t:Mailbox>'+
    '          </t:ToRecipients>'+
    '        </t:Message>'+
    '      </m:Items>'+
    '    </m:CreateItem>'+
    '  </soap:Body>'+
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
    console.log(result);
});

removeHandlerAsync(eventType, options, callback)

Remove um manipulador de eventos para um tipo de evento com suporte. Nota: os eventos só estão disponíveis com a implementação do painel de tarefas.

Para eventos suportados, veja a secção Eventos do modelo de objetos da Caixa de Correio.

removeHandlerAsync(eventType: Office.EventType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parâmetros

eventType: Office.EventType | string

O evento que deve revogar o manipulador.

options: Office.AsyncContextOptions

Fornece uma opção para preservar dados de contexto de qualquer tipo, inalterados, para utilização numa chamada de retorno.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro do tipo Office.AsyncResult.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.5 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

removeHandlerAsync(eventType, callback)

Remove um manipulador de eventos para um tipo de evento com suporte. Nota: os eventos só estão disponíveis com a implementação do painel de tarefas.

Para eventos suportados, veja a secção Eventos do modelo de objetos da Caixa de Correio.

removeHandlerAsync(eventType: Office.EventType | string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parâmetros

eventType: Office.EventType | string

O evento que deve revogar o manipulador.

callback: (asyncResult: Office.AsyncResult<void>) => void

Opcional. Quando o método for concluído, a função transmitida no callback parâmetro é chamada com um único parâmetro do tipo Office.AsyncResult.

Retornos

void

Comentários

[ Conjunto de API: Caixa de Correio 1.5 ]

Nível mínimo de permissão: ler item

Modo Outlook aplicável: Compose ou Leitura

Exemplos

Office.context.mailbox.removeHandlerAsync(Office.EventType.OfficeThemeChanged, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error("Failed to remove event handler: " + asyncResult.error.message);
        return;
    }

    console.log("Event handler removed successfully.");
});

Compartilhar via

Office.Mailbox interface

Comentários

Exemplos

Propriedades

Métodos

Detalhes da propriedade

diagnostics

Valor da propriedade

Comentários

Exemplos

ewsUrl

Valor da propriedade

Comentários

Exemplos

item

Valor da propriedade

masterCategories

Valor da propriedade

Comentários

Exemplos

restUrl

Valor da propriedade

Comentários

Exemplos

userProfile

Valor da propriedade

Detalhes do método

addHandlerAsync(eventType, handler, options, callback)

Parâmetros

Retornos

Comentários

Exemplos

addHandlerAsync(eventType, handler, callback)

Parâmetros

Retornos

Comentários

convertToEwsId(id, restVersion)

Parâmetros

Retornos

Comentários

Exemplos

convertToLocalClientTime(timeValue)

Parâmetros

Retornos

Comentários

convertToRestId(id, restVersion)

Parâmetros

Retornos

Comentários

Exemplos

convertToUtcClientTime(input)

Parâmetros

Retornos

Comentários

Exemplos

displayAppointmentForm(itemId)

Parâmetros

Retornos

Comentários

Exemplos

displayMessageForm(itemId)

Parâmetros

Retornos

Comentários

Exemplos

displayNewAppointmentForm(parameters)

Parâmetros

Retornos

Comentários

Exemplos

displayNewMessageForm(parameters)

Parâmetros

Retornos

Comentários

Exemplos

getCallbackTokenAsync(options, callback)

Parâmetros

Retornos

Comentários