Il presente articolo è stato tradotto automaticamente.
Microsoft Office
Analisi dell'API JavaScript per Office: app di posta elettronica
Questo articolo è la quarta parte di un'analisi approfondita dell'API JavaScript per l'ufficio, concentrandosi sulla parte dell'API disponibili per le applicazioni di posta supportati da Outlook e Outlook Web App. Presumo che hai qualche comprensione generale delle applicazioni per l'ufficio. In caso di dubbio, leggendo la pagina di documentazione Dev Center, "Panoramica delle applicazioni per ufficio" (bit.ly/12nBWHG), si imposterà sulla strada giusta. Parte 1 di questa serie, "Exploring the New JavaScript API per Office" (msdn.microsoft.com/magazine/jj891051), fornisce una panoramica di alto livello del modello a oggetti, che ha l'ufficio in oggetto come l'oggetto principale. L'oggetto cassetta postale, appesi fuori dal Office.context, offre un punto di ingresso per la maggior parte delle funzionalità specifiche app posta nel modello a oggetti, e questo è dove potrai ritirare la discussione.
L'asporto chiave di questo articolo è quello che, lo sviluppatore può fare con l'API JavaScript per ufficio in applicazioni di posta. Ho anche fornito un articolo online compagno in cui cammino attraverso un'applicazione di posta esempio, completo di codice sorgente, a msdn.microsoft.com/magazine/dn205107. Ora, mi occuperò di varie funzioni dell'API JavaScript per l'ufficio, partendo con alcune delle tecniche più fondamentali, comunemente usate e poi passare a concetti più avanzati.
Caratteristiche fondamentali dell'API JavaScript per ufficio
L'oggetto cassetta postale consente di accedere al profilo utente, l'elemento attualmente selezionato dall'utente, forme di visualizzazione dell'elemento e un sottoinsieme di servizi Web Exchange (EWS) per manipolare gli elementi e le cartelle nella cassetta postale. L'elemento oggetto rappresenta l'elemento selezionato di messaggio o di un appuntamento. Attraverso tale oggetto, è possibile accedere ulteriori proprietà incorporate, proprietà personalizzate e allegati di tale elemento.
Controllo attivazione basata sul tipo di elemento è possibile definire regole nel manifesto per determinare quando attivare un app mail. L'elemento attualmente selezionato dall'utente e specificata da Mailbox.item può essere un messaggio (comprese le convocazioni di riunione, risposte e annullamenti) o un oggetto nomina. A seconda del tuo scenario, è possibile limitare l'applicazione mail per attivare per solo un tipo di elemento specifico. Nell'esempio di XML seguente viene illustrato una regola di attivazione ItemIs che limita l'applicazione mail per attivare solo per i messaggi:
<Rule xsi:type="ItemIs" ItemType="Message" />
Utilizzando l'API JavaScript per Office, è possibile utilizzare la proprietà itemType per verificare il tipo dell'elemento selezionato:
Office.context.mailbox.item.itemType
Punto di accesso e proprietà una funzione di base offerto da applicazioni di posta elettronica è l'accesso dell'elemento attualmente selezionato e le relative proprietà incorporata.
Nell'esempio JavaScript seguente viene illustrato come accedere l'elemento selezionato e la sua proprietà incorporata, soggetto:
// The initialize function is required for all apps.
Office.initialize = function () {
// Check for the DOM to load.
$(document).ready(function () {
var item = Office.context.mailbox.item;
var subject = item.subject;
// Continue processing the subject.
});
}
Entità ben noto Exchange Server riconosce alcune entità che sono disponibili indipendentemente dal fatto se usato entità per attivare l'applicazione di posta elettronica. Outlook e Outlook Web App estrarre queste entità se esistono nell'oggetto o nel corpo dell'elemento selezionato e li rendono disponibili attraverso i seguenti metodi di API JavaScript:
- Metodo getEntities
- Metodo getEntitiesByType(entityType)
- Metodo getFilteredEntitiesByName(name)
Entità supportate comprendono indirizzo, contatto, indirizzo e-mail e altro ancora.
Si noti che Outlook e Outlook Web App estrarre stringhe solo in inglese indipendentemente dal locale predefinito che è specificare nel manifesto dell'applicazione. Essi non possono estrarre entità nella cartella Posta inviata. E si possono estrarre suggerimenti riunione nei messaggi, ma non nelle nomine.
Sempre partite che risultato in attivazione contestuale è possibile specificare le regole di attivazione che dipendono da partite di regular expression (ItemHasRegularExpressionMatch regole) o entità corrisponde (ItemHasKnownEntity rules) dell'elemento selezionato. È possibile utilizzare i metodi seguenti per ottenere corrispondenze di espressioni regolari. Questi metodi sono disponibili sull'oggetto elemento genitore, può essere un messaggio o un appuntamento:
- Metodo getRegExMatches
- Metodo getRegExMatchesByName(name)
È possibile utilizzare i metodi elencati nella sezione entità ben noto per ottenere corrispondenze entità specifica. Si noti che è sempre possibile utilizzare questi metodi per ottenere qualsiasi entità partite indipendentemente dal tipo di regole di attivazione, che è possibile utilizzare per l'applicazione di posta.
Esempi il seguente è un esempio di una regola di ItemHasRegularExpressionMatch, denominato VideoURL, che attiva l'applicazione di posta elettronica se l'elemento selezionato è un messaggio e il corpo del messaggio contiene un URL di un video su YouTube:
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" ItemType="Message"/>
<Rule xsi:type="ItemHasRegularExpressionMatch"
RegExName="VideoURL"
RegExValue="http://www\.youtube\.com/watch\?v=[a-zA-Z0-9_-]{11}"
PropertyName="Body"/>
</Rule>
Nell'esempio di codice JavaScript viene illustrato come utilizzare il metodo Item.getRegExMatches per ottenere le corrispondenze dell'espressione regolare precedente VideoURL:
Office.initialize = function () {
// Check for the DOM to load.
$(document).ready(function () {
// Get an array of string matches for the regular expression VideoURL,
// as specified in the manifest.
var matches = Office.context.mailbox.item.getRegExMatches().VideoURL;
// Continue processing the matches for the regular expression.
});
}
Di seguito è riportato un esempio di una regola di ItemHasKnownEntity che attiva l'app mail se un indirizzo è presente l'oggetto o il corpo di un messaggio:
<Rule xsi:type="RuleCollection" Mode="And">
<Rule xsi:type="ItemIs" ItemType="Message"/>
<Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>
Nell'esempio di codice JavaScript di seguito viene illustrato l'utilizzo del metodo getEntitiesByType per ottenere una matrice di stringhe che sono indirizzi postali nel soggetto o nel corpo del messaggio selezionato:
Office.initialize = function () {
// Check for the DOM to load.
$(document).ready(function () {
var item = Office.context.mailbox.item;
// Get an array of strings that represent postal
// addresses in the current item.
var addresses = item.getEntitiesByType(
Office.MailboxEnums.EntityType.Address);
// Continue processing the array of addresses.
});
}
Attivazione di un'applicazione di posta elettronica basato su contesti — espressione regolare soprattutto partite o l'esistenza di entità ben noto — è potente e può essere complicato per eseguire il debug. Vedere l'articolo MSDN Library "Attivazione apps Troubleshooting posta," a bit.ly/11C0H30 per suggerimenti su come eseguire il debug di problemi di attivazione.
Archiviazione dati Per elemento Per App CustomProperties l'oggetto consente di memorizzare i dati specifici dell'elemento che può accedere solo l'applicazione di posta come una proprietà personalizzata sull'elemento in una sessione successiva. Tali dati sono rappresentati come coppie chiave-valore. Se l'app è progettato per funzionare su più client Outlook e fattori di forma, le proprietà personalizzate vagano con il fattore di forma e client Outlook supportato.
Le proprietà personalizzate di un elemento sono disponibili tramite il metodo Item.loadCustomPropertiesAysnc. Questo è un metodo asincrono che utilizza un metodo di callback come parametro. Quando vengono caricate le proprietà personalizzate, sono disponibili tramite la proprietà asyncResult.value, che viene passata al metodo di callback come parametro di input. Figura 1 di seguito viene illustrato come caricare, ottenere, impostare e salvare le proprietà personalizzate per l'elemento corrente.
Figura 1 lavorando con proprietà personalizzate per l'elemento corrente
Office.initialize = function () {
var mailbox = Office.context.mailbox;
mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
}
function customPropsCallback(asyncResult) {
if (asyncResult.status == Office.AsyncResultStatus.Succeeded) {
var customProps = asyncResult.value;
var myProp = customProps.get("myProp");
customProps.set("otherProp", "value");
customProps.saveAsync(saveCallback);
}
else {
write (asyncResult.error.message);
}
}
function saveCallback(asyncResult) {
// Callback method to save custom properties.
}
Archiviazione dati Per cassetta postale Per App RoamingSettings l'oggetto consente di memorizzare i dati personalizzati che l'applicazione di posta può accedere per la stessa cassetta postale indipendentemente dal fatto che l'applicazione di posta elettronica sia in esecuzione su un desktop, tablet o smartphone. Nell'esempio JavaScript seguente viene illustrato come ottenere dati specifici delle cassette postali nel gestore dell'evento initialize dell'app mail:
var _mailbox;
var _settings;
Office.initialize = function () {
// Check for the DOM to load using the jQuery ready function.
$(document).ready(function () {
// Initialize instance variables to access API objects.
_mailbox = Office.context.mailbox;
_settings = Office.context.roamingSettings;
// Continue with app-specific code.
});
}
Profilo utente si può accedere al profilo dell'utente utilizzando la proprietà Office.context.mailbox.userProfile. Attraverso l'oggetto UserProfile, è possibile ottenere il nome visualizzato, indirizzo SMTP e il fuso orario locale dell'utente firmato-in. Nell'esempio di codice JavaScript seguente viene illustrato come accedere alla proprietà UserProfile.emailAddress dell'utente corrente firmato Outlook o Outlook Web App:
Office.initialize = function () {
// Check for the DOM to load.
$(document).ready(function () {
var userProfile = Office.context.mailbox.userProfile;
var SMTPAddress = userProfile.emailAddress;
// Continue with processing the user's SMTP address.
});
}
Visualizzazione di Outlook Form l'utente può specificare il form per visualizzare gli appuntamenti e i messaggi per impostazione predefinita In Outlook. Utilizzando i metodi seguenti nell'API JavaScript per l'ufficio, un app mail può visualizzare un appuntamento e messaggio rispettivamente, usando le stesse forme che Outlook utilizza:
- Mailbox.displayAppointmentForm(itemId)
- Mailbox.displayMessageForm(itemId)
Il codice in Figura 2 controlli per vedere se l'utente ha selezionato un appuntamento e vengono visualizzati con l'Outlook predefinito modulo di nomina.
Figura 2 verifica per vedere se l'utente ha selezionato un appuntamento
var myOm;
var myItem;
Office.initialize = function () {
$(document).ready(function () {
myOm = Office.context.mailbox;
// Get the selected item.
myItem = myOm.item;
// Display the selected appointment.
displaySelectedAppointment();
});
}
function displaySelectedAppointment() {
// Display selected item only if the item is an appointment.
if (myitem.itemType == Office.MailboxEnums.ItemType.Appointment)
{
myOm.displayAppointmentForm(myItem.itemId);
}
else
{
// Handle condition as appropriate.
}
}
Il metodo Mailbox.displayNewAppointmentForm consente di assegnare valori di determinati campi in una forma di appuntamento per una nuova riunione e visualizzare il form per l'utente a compilare la nomina. Quando si chiama questo metodo, specificare questi campi come un elenco di coppie valore-stringa, come mostrato Figura 3.
Figura 3 assegnando valori ai campi specifici in una nuova forma di nomina
var myOm;
Office.initialize = function () {
$(document).ready(function () {
myOm = Office.context.mailbox;
// After the DOM is loaded, can display the
// pre-populated new appointment form.
displayFormForNewAppointment();
});
}
function displayFormForNewAppointment(){
var formParameters =
{
"requiredAttendees" : ["wendy@contoso.com", "derek@contoso.com"],
"optionalAttendees" : ["shane@contoso.com", "michael@contoso.com"],
"start" : new Date("September 27, 2012 11:15:00"),
"end" : new Date("("September 27, 2012 12:30:00"),
"location" : "Conf room 200",
"resources" : ['sound', 'lighting', 'recording'],
"subject" : "Next rehearsal",
"body" : "This is about the next rehearsal."
}
// Display a form to create an appointment with
// the specified fields in the form.
myOm.displayNewAppointmentForm(formParameters);
}
I metodi che visualizzano le forme di risposta a un messaggio o un appuntamento di offrire maggior margine di personalizzazione:
- Metodo Appointment.displayReplyAllForm(htmlBody)
- Metodo Appointment.displayReplyForm(htmlBody)
- Metodo Message.displayReplyAllForm(htmlBody)
- Metodo Message.displayReplyForm(htmlBody)
Con ciascuno di questi metodi, è possibile fornire una stringa HTML che rappresenta il corpo del modulo di risposta. L'esempio in Figura 4 viene visualizzato un form Rispondi a tutti per un messaggio.
Figura 4 specificando il codice HTML per un risposta-tutti in forma per un elemento del messaggio
var myOm;
var myItem;
Office.initialize = function () {
// Check for the DOM to load.
$(document).ready(function () {
myOm = Office.context.mailbox;
// Get the selected item.
myItem = myOm.item;
// After the DOM is loaded, display
// the reply form.
displayReply();
});
}
function displayReply(){
// Display a reply form to the sender and recipients only
// if the selected item is a message.
if (myitem.itemType == Office.MailboxEnums.ItemType.Message) {
myItem.displayReplyAllForm
("<html><head><head><body>This is the body of " +
"the email reply.</body></html>");
}
}
Concetti avanzati
Ottenere gli allegati degli elementi una mail app possono utilizzare l'API JavaScript per ufficio ed EWS gettoni di callback per accedere gli allegati del messaggio selezionato o appuntamento nella cassetta postale dell'utente. L'utilizzo del token richiamata consente al codice di back-end, server-side dell'app mail — o servizi di terze parti Web — per chiamare l'operazione EWS, GetAttachment, effettivamente ottenere gli allegati specifici.
La seguente descrive come un app mail ottiene gli allegati (questo processo è illustrato anche Figura 5):
- Un'applicazione di posta utilizza Mailbox.getCallbackTokenAsync per richiedere un token di callback, utilizza Item.attachments per ottenere i metadati relativi allegati del messaggio (compresi allegati IDs) o appuntamento selezionato e utilizzato Mailbox.ewsUrl per ottenere l'URL dell'endpoint EWS per l'account di posta elettronica corrente.
- L'app mail passa il token di callback, allegato ID e l'URL dell'endpoint EWS al codice lato server.
- Il codice lato server chiama l'operazione GetAttachment EWS per ottenere l'effettivi allegati da tale archivio di Exchange.
.png)
Figura 5 Mail Apps accesso allegati da un Exchange Server
Si noti che il codice sul lato server dovrà accedere EWS creando direttamente le richieste di EWS. Non è possibile utilizzare il Mailbox.makeEwsRequestAsync metodo per accedere all'operazione GetAttachment. A partire da questa scrittura, l'accesso degli allegati è supportato se l'app mail funziona su Outlook Web App. La funzione non è disponibile se si esegue l'applicazione di posta elettronica in Outlook.
Vedere l'esempio di codice MSDN, "Mail applicazioni per ufficio: Ottenere gli allegati da un server di Exchange"(bit.ly/11dG9fS), per un esempio di come accedere gli allegati in un'applicazione di posta elettronica.
Token utente per Single Sign-On tua mail app possono utilizzare comuni tecniche di autenticazione Web di autenticare e autorizzare gli utenti. Se si desidera supportare l'autenticazione single sign-on per gli utenti attraverso Outlook e Outlook Web App, è possibile utilizzare il token di identità Exchange chiamando il metodo Mailbox.getUserIdentityTokenAsync.
Single sign-on è basato su un Exchange Server assegnando un token di identità di scambio per account di posta elettronica dell'utente sul Exchange Server. Un token di identità Exchange contiene più campi, tra i quali sono una firma per la convalida del token e un identificatore univoco che rappresenta l'account di posta elettronica di Exchange.
In generale, un'applicazione di posta che autentica gli utenti può interagire con un servizio Web, che può essere il codice lato server per la posta app — o un servizio Web di terze parti, che utilizza il proprio Provider di identità (IdP) per convalidare l'identità dell'utente in un sistema di identità federata. La chiave per single sign-on è la mappatura che il servizio Web mantiene tra l'ID univoco (dal token di identità Exchange) e l'identità dell'utente (che è noto per l'IdP).
Figura 6 fornisce una descrizione ad alto livello di usare Exchange identità token per l'autenticazione.
Il seguente riassume il processo:
- L'app mail chiama Mailbox.getUserIdentityTokenAsync per richiedere un token di identità di Exchange per l'utente, se si specifica un metodo di callback che viene eseguito quando l'operazione get asincrona viene completata.
- La funzione di callback ottiene l'identità di Exchange token e lo passa al servizio Web per l'autenticazione.
- Il servizio Web ottiene una chiave pubblica da Exchange Server per convalidare il token.
- A seconda se l'utente ha firmato prima, il servizio Web si procede come segue:
- Se è la prima volta che l'utente segni per l'applicazione di posta elettronica, alcuna mappatura preventiva non esiste per quell'account, e il servizio Web risponde alle mail app per richiedere all'utente le credenziali. Dopo aver ricevuto le credenziali, l'app mail li passa al servizio Web.
- Il servizio crea quindi un mapping tra l'ID univoco fornito dal token e l'identità dell'utente dalle credenziali che gli sono ben noti per l'IdP. Utilizzando le credenziali, il servizio può accedere l'utente.
- In tempi successivi: Quando l'utente apre l'applicazione di posta elettronica in Outlook o Outlook Web App da desktop, browser su uno smartphone o tablet, si verificano i seguenti passaggi:
- L'app mail chiama getUserIdentityTokenAsync e ottiene lo stesso ID univoco nel token
- L'app mail passa il token al servizio Web.
- Il servizio Web convalida token.
- Il servizio Web quindi cerca la tabella di mapping, trova l'utente e autorizza l'accesso.
.png)
Figura 6 l'autenticazione utilizzando Exchange identità token
Una volta che si convalida il token, è possibile mantenere l'utente loggato, anche quando l'utente apre l'app posta da un'altra applicazione host o dispositivo.
I dettagli per l'autenticazione e validazione sono abbastanza complessi. È possibile utilizzare una libreria EWS Managed API convalida per semplificare il processo. Utilizzando tale libreria di convalida, un servizio Web sarebbe creare un oggetto, estrarre e mettere il token in oggetto, verificare se la firma è valida e se è valido, quindi mettere l'identificatore univoco nel database di mappatura.
Per ulteriori informazioni sull'utilizzo di token di identità di Exchange per l'autenticazione, vedere la seguente documentazione Dev Center:
- "Autenticazione un app mail utilizzando il token di identità Exchange" (bit.ly/ZYaZ9v)
- "All'interno del token di identità Exchange" (bit.ly/ZxRogq)
- "Come: Chiamare un servizio utilizzando un token identità in Exchange"(bit.ly/12jqxcU)
- "Come: Utilizzare la libreria di convalida token Exchange"(bit.ly/11akmEg)
- "Come: Convalidare un token di identità Exchange"(bit.ly/15im6SO)
- "Come: Autenticare un utente con un token di identità per Exchange"(bit.ly/13gZ36T)
Per esempi di codice:
- È possibile fare riferimento a "Mail apps per Outlook: Utilizzare un token di identità client"campione in c# per Visual Studio 2012 (bit.ly/ZxS85b) per un C# esempio di un'applicazione di posta e un servizio Web che utilizzano Exchange identità token per l'autenticazione.
- Vedere "applicazioni di posta di Outlook: Convalidare un token di identità client utilizzando il Framework .NET"(bit.ly/17j9FSZ) per un esempio di come utilizzare il Framework .NET per convalidare Exchange client identity token.
Accesso a un sottoinsieme di EWS utilizzando il metodo Mailbox.makeEwsRequestAsync, applicazioni di posta possono accedere un sottoinsieme delle operazioni EWS per creare, trovare, ottenere, aggiornare, spostare o inviare un elemento o una cartella. Ad esempio, è possibile utilizzare l'operazione CreateItem per creare un appuntamento, messaggio o contatto. È possibile utilizzare l'operazione FindItem per cercare gli elementi in una cassetta postale. Ed è possibile utilizzare l'operazione SendItem per inviare un messaggio o incontro invito. Il sottoinsieme supportato delle operazioni riguarda solo cassetta postale dell'utente. Altre operazioni di EWS che riguardano un'intera organizzazione — come accedere l'elenco indirizzi globale o scorrere ogni persona dell'organizzazione — sono off-limits per applicazioni di posta elettronica. Inoltre, poiché il sottoinsieme supportato di operazioni è potente, apps mail deve richiedere autorizzazioni cassetta postale in lettura/scrittura nel manifesto dell'applicazione, e solo gli amministratori possono installare applicazioni di posta che richiedono tale autorizzazione.
Quando si chiama il metodo Mailbox.makeEwsRequestAsync, stai chiedendo EWS su Exchange Server che ospita la cassetta postale dell'utente. Prima di chiamare makeEwsRequestAsync, specificare argomenti di input per i seguenti parametri:
- parametro di dati: Creare una richiesta SOAP XML per l'operazione di EWS che si intende chiamare.
- parametro callback: Un metodo di callback che vuoi gestire la risposta dell'operazione.
- parametro userContext: Qualsiasi input dati per il metodo di callback.
Al termine dell'operazione, le apps per quadro ufficio chiama il metodo di callback con un argomento, che è un oggetto AsyncResult, simile agli altri metodi asincroni che hai visto nella prima parte di questa serie. Il metodo di callback può accedere l'Asyncproprietà Result.value per ottenere la risposta SOAP XML contenente i dati relativi all'operazione. Il metodo di callback può anche accedere alla proprietà AsyncResult.asyncContext per accedere a qualsiasi altro parametro di input passato tramite il parametro userContext. Il metodo di callback analizza poi il XML nella risposta SOAP per ottenere i dati pertinenti per i suoi scopi.
Per un elenco completo delle operazioni supportate EWS e ulteriori dettagli, vedere la documentazione di Dev Center, "Chiamata Web services da un'applicazione di posta elettronica per Outlook" (bit.ly/12jtH0z).
Per un esempio di un'applicazione di posta che illustri la chiamata l'operazione GetItem, vedere "posta apps per Outlook: Effettuare una richiesta EWS"campione in c# per Visual Studio 2012 (bit.ly/Zv3hEQ).
Conclusioni
Che avvolge la mia discussione di costruzione di applicazioni di posta, come pure l'esplorazione in quattro parti dell'API JavaScript per l'ufficio. Per le rate precedenti in questa serie e l'articolo compagno on-line per questa puntata, vedere:
- "Esplorare la nuova API JavaScript per ufficio" a msdn.microsoft.com/magazine/jj891051
- "Esplorando l'API JavaScript per Office: Accesso ai dati e gli eventi"a msdn.microsoft.com/magazine/jj991976
- "Esplorando l'API JavaScript per Office: Associazione dati e parti XML personalizzati"a msdn.microsoft.com/magazine/dn166930
- "Esplorando l'API JavaScript per Office: Un esempio Mail App"a msdn.microsoft.com/magazine/dn205107
Angela Chu-Hatoun iniziato come uno sviluppatore di software e passato a scrivere per il suo interesse maggiore che spiega come funziona il software. Lei è stato uno scrittore programmatore nella divisione Office per 12 anni e scrive per gli sviluppatori di creare applicazioni per Office e altre soluzioni per Outlook. Ama leggere su current affairs, giardinaggio, viaggi, cibo e moda.
Grazie ai seguenti esperti tecnici per la revisione di questo articolo: Andrew Salamatov (Microsoft) e Tim Wan (Microsoft)
Tim WAN graduato da Caltech nel 2003 e ha conseguito una laurea in ingegneria e scienze applicate. Per gli ultimi nove anni è stato uno sviluppatore di software in Outlook. Ha lavorato estensivamente la caratteristica di apps di posta in Outlook 2013, come pure il modello oggetti di Outlook nelle versioni precedenti. Egli guarda avanti a portare nuove funzionalità e miglioramenti ai clienti in tutto il mondo.