Create a Cordova App using O365 Outlook Services and Ionic

Article
04/15/2015

Dans ce didacticiel, vous allez apprendre à créer un client de messagerie, de calendrier et de contacts à l'aide des services Outlook O365 et de l'infrastructure Ionic. Cette application permet aux utilisateurs d'accéder à leur courrier, leur calendrier et leurs contacts via l'API des services Outlook O365. Cet exemple utilise du code JavaScript, mais vous pouvez également écrire votre application Cordova en TypeScript.

Dans ce didacticiel, vous allez procéder comme suit :

Créer un projet
Ajouter l'infrastructure Ionic à votre projet
Ajouter NProgress à votre projet
Ajouter des services O365 à votre application
Définir des autorisations pour le courrier, le calendrier et les contacts O365, afin d'accorder l'accès approprié à votre application
Créer la structure des dossiers d'application, le routage de l'interface utilisateur et la disposition à l'aide de contrôles Ionic
Acquérir un jeton d'accès et obtenir le client des services Outlook à l'aide de la fabrique AngularJS
Utilisez l'API O365 pour récupérer les données de service Outlook :
- Pour l'application Courrier, les courriers signalés comme étant importants, les courriers non lus et tous les courriers
- Pour l'application Calendrier, réunion du jour (date de début d'événement égale à aujourd'hui), réunion de demain (date de début d'événement égale à demain) et tous les événements dont la date de début est postérieure ou égale à la date du jour
- Pour l'application Contacts, tous les contacts
Utilisez l'API O365 pour créer et supprimer des données :
- Supprimer du courrier, un événement de calendrier
- Créer un événement de calendrier, un contact
Exécuter l'application

La capture d'écran suivante montre l'application Calendrier en cours d'exécution une fois que tout est terminé.

La capture d'écran suivante montre l'application Courrier en cours d'exécution une fois que tout est terminé.

La capture d'écran suivante montre l'application Contacts en cours d'exécution une fois que tout est terminé.

Composants requis

Avant de pouvoir créer un projet, assurez-vous que vous disposez de la configuration système requise et que vous avez installé l'extension Visual Studio Tools for Apache Cordova. Pour plus d'informations, voir Installer Visual Studio Tools for Apache Cordova

Créer un projet

Créez un projet Cordova dans Visual Studio en choisissant Fichier, Nouveau projet, JavaScript, Applications Apache Cordova, puis le modèle Application vide.

Ajouter l'infrastructure Ionic à votre projet

Pour ajouter l'infrastructure Ionic

Sur le site web de l'infrastructure Ionic, choisissez le lien permettant de télécharger la bêta.
Extrayez le fichier zip.
Créez un dossier nommé lib sous votre projet Cordova dans l'Explorateur de solutions de Visual Studio, puis copiez le contenu extrait sous le dossier lib.
Mettez à jour les références de script.

Dans index.html, ajoutez les références Ionic suivantes dans l'élément <head>, après les références de script Cordova et platformOverrides.
```
<script src="lib/ionic/js/ionic.bundle.min.js"></script>
```
Dans index.html, ajoutez la référence CSS ionic suivante.
```
<link href="lib/ionic/css/ionic.min.css" rel="stylesheet" />
```

Ajouter NProgress à votre projet

NProgress est utilisé pour afficher une barre de progression durant la récupération du courrier, du calendrier et des contacts via O365.

Pour ajouter NProgress à votre projet

Sur le site web NProgress, choisissez Download.
Extrayez le fichier zip.
Créez un dossier nommé nprogress sous le dossier lib dans l'Explorateur de solutions, puis copiez nprogress.js dans ce dossier.
Copier nprogress.css sous le dossier css

Dans index.html, ajoutez les références NProgress suivantes dans l'élément <head>.

<link href="css/nprogress.css" rel="stylesheet" />
<script src="lib/nprogress/nprogress.js"></script>

Ajouter des services O365 à votre application

Inscrivez-vous à un Site du développeur Office 365 et configurez l'accès Azure Active Directory pour votre site de développeur en suivant les instructions indiquées dans Configurer votre environnement de développement Office 365.

Une fois que vous avez configuré votre site de développeur, procédez comme suit pour ajouter et configurer les API Office 365 à l'aide du Gestionnaire de services de Visual Studio.

Pour ajouter et configurer des API Office 365

Téléchargez et installez les outils d'API Office 365 à partir de la Galerie Visual Studio.
Dans le menu contextuel du nœud de projet, choisissez Ajouter, puis Service connecté.
En haut de la boîte de dialogue Gestionnaire de services, choisissez le lien Office 365, puis Inscrire votre application.

Connectez-vous avec un compte d'administrateur client pour votre organisation de développement Office 365.

Définir des autorisations pour le courrier, le calendrier et les contacts O365, afin d'accorder l'accès approprié à l'application

Une fois que vous vous êtes connecté au compte O365, vous voyez s'afficher une liste de services O365, tels que le courrier, le calendrier, les contacts, ainsi que des fichiers, sous votre compte de locataire. Sélectionnez le service à utiliser dans votre application, puis définissez l'autorisation à laquelle vous souhaitez que votre application accède, comme indiqué ci-dessous pour chaque application.

Application Courrier

Sélectionnez Courrier, puis cliquez sur le lien Autorisations dans le volet droit. Choisissez ensuite les autorisations de lecture et d'écriture du courrier de l'utilisateur, car l'application devra effectuer des opérations de lecture et de suppression du courrier. De même, si vous souhaitez que l'application envoie du courrier, sélectionnez courrier en tant qu'option utilisateur.

Application Calendrier

Sélectionnez Calendrier, cliquez sur le lien Autorisations dans le volet droit, puis sélectionnez avoir un accès complet au calendrier des utilisateurs. De même, si vous souhaitez accorder uniquement un accès en lecture à l'application, sélectionnez Lire le calendrier des utilisateurs.

Application Contacts

Sélectionnez Contacts, cliquez sur le lien Autorisations dans le volet droit, puis sélectionnez avoir un accès complet aux contacts des utilisateurs. De même, si vous souhaitez accorder uniquement un accès en lecture à l'application, sélectionnez Lire les contacts des utilisateurs.

Appliquer des changements et mettre à jour des références

Pour appliquer des changements et mettre à jour des références

Cliquez sur Appliquer, puis sur OK pour définir les autorisations, et ajouter l'API O365 à votre projet.

Le Gestionnaire de services ajoute le dossier services à votre projet.

Dans index.html, ajoutez les références O365 suivantes dans l'élément <head>.

<script src="services/office365/scripts/o365loader.js"></script>
<script src="services/office365/settings/settings.js"></script>

Procédez comme suit pour structurer l'interface utilisateur de l'application et le code JavaScript.

Créez un dossier nommé application sous le nœud racine du projet. Le dossier application contient les fichiers spécifiques à l'application. Chaque composant d'interface utilisateur qui récupère et lie des données à l'interface utilisateur a un contrôleur correspondant (en suivant le modèle de l'interface utilisateur avec code-behind). Par exemple, mail-list.html présente un contrôle de liste qui permet d'afficher les e-mails de l'utilisateur. Par ailleurs, mail-list-ctrl.js contient du code qui permet de récupérer le courrier de l'utilisateur via l'API O365.

Voici quelques détails sur les dossiers et fichiers du projet.

Le dossier auth contient l'interface utilisateur, ainsi que le code de connexion et de déconnexion.
Le dossier layout contient l'interface utilisateur qui permet d'afficher le contenu de l'application et des éléments de navigation, par exemple ion-pane, ion-side-menus, ion-nav-bar, ainsi que du code permettant de lier le nom d'utilisateur.
app.js contient l'interface utilisateur de routage pour naviguer vers différentes pages.
service-o365.js contient des fonctions utilitaires pour obtenir le jeton d'accès, créer l'objet client des services Outlook, se déconnecter, et récupérer le nom d'utilisateur. Cela est implémenté en tant que fabrique AngularJS pour que ces fonctions puissent être exposées sous forme de fonctions utilitaires dans différentes pages.

Utilisez le routage AngularJS pour naviguer vers différentes pages. Par exemple, voici le routage pour l'application Courrier.

// Layout page
    .state('app', {
        abstract: true,
        url: "/app",
        templateUrl: "app/layout/layout.html"
    })

    // Sign-in page
     .state('sign-in', {
         url: "/sign-in",
         templateUrl: "app/auth/sign-in.html"
     })

    // Sign-out page
        .state('app.sign-out', {
            url: "/sign-out",
            views: {
                'mainContent': {
                    templateUrl: "app/auth/sign-out.html"
                }
            }
        })   

    // Mail list page
    .state('app.mail', {
        url: "/mail",
        views: {
            'mainContent': {
                templateUrl: "app/mail/mail-tabs.html"
            }
        }
    })

    // Mail list containing mails flagged as important
    .state('app.mail.imp', {
        url: "/imp/id:important",
        views: {
            "tab-imp-mail": {
                templateUrl: "app/mail/mail-list.html"
            }
        }
    })

    // Mail detail page
    .state('app.mail-detail', {
        url: "/mail/:id",
        views: {
            'mainContent': {
                templateUrl: "app/mail/mail-detail.html"
            }
        }
    })

    // Unread mail list page
    .state('app.mail.unread', {
        url: "/unread/id:unread",
        views: {
            "tab-unread-mail": {
                templateUrl: "app/mail/mail-list.html"
            }
        }
    })

    // All mail list page
    .state('app.mail.all', {
        url: "/all/id:all",
        views: {
            "tab-all-mail": {
                templateUrl: "app/mail/mail-list.html"
            }
        }
    });

    // Navigate to sign-in page when app starts.
    $urlRouterProvider.otherwise('sign-in');

Pour la disposition d'application (menu, barre de navigation), utilisez le menu latéral et le volet Ionic.

<ion-side-menus ng-controller="layoutCtrl as vm">

    <ion-pane ion-side-menu-content>
        <ion-nav-bar class="bar-positive">
            <ion-nav-back-button class="button-clear icon ion-ios7-arrow-back"></ion-nav-back-button>
            <button menu-toggle="left" class="button button-icon icon ion-navicon"></button>
        </ion-nav-bar>
        <ion-nav-view name="mainContent" animation="slide-left-right"></ion-nav-view>
    </ion-pane>

    <ion-side-menu side="left">
        <header class="bar bar-header bar-positive">
            <h1 class="title">{{vm.userName}}</h1>
        </header>
        <ion-content class="has-header">
            <ion-list>                            
                <ion-item nav-clear menu-close ui-sref="app.sign-out">Sign-out</ion-item>
            </ion-list>
    </ion-side-menu>

</ion-side-menus>

Utilisez l'onglet Ionic pour afficher du contenu distinct sous des onglets séparés. Par exemple, utilisez les contrôles Ionic ci-dessous pour créer une page d'onglet courrier qui affiche les e-mails importants, les e-mails non lus et tous les autres e-mails sous des onglets distincts.

<ion-view>
    <ion-tabs class="tabs-positive tabs-icon-top">
        <ion-tab title="Imp" icon="ion-star" ui-sref="app.mail.imp">
            <ion-nav-view name="tab-imp-mail"></ion-nav-view>
        </ion-tab>

        <ion-tab title="Unread" icon="ion-ios7-email-outline" ui-sref="app.mail.unread">
            <ion-nav-view name="tab-unread-mail"></ion-nav-view>
        </ion-tab>

        <ion-tab title="All" icon="ion-email" ui-sref="app.mail.all">
            <ion-nav-view name="tab-all-mail"></ion-nav-view>
        </ion-tab>
    </ion-tabs>
</ion-view>

L'illustration suivante présente la page d'onglet courrier.

Acquérir un jeton d'accès et obtenir le client des services Outlook à l'aide de la fabrique AngularJS

Créez une fabrique AngularJS pour exposer l'API O365 et acquérir un jeton d'accès, créer le client des services Outlook, vous déconnecter, puis exécuter d'autres fonctions utilitaires utilisées par différents contrôleurs de l'application.

Voici le code permettant d'acquérir un jeton d'accès.

var authContext = new O365Auth.Context();
authContext.getIdToken("https://outlook.office365.com/")
.then((function (token) {
     // Get auth token
     authtoken = token;
     // Get user name from token object.
     userName = token.givenName + " " + token.familyName;
    }), function (error) {
      // Log sign-in error message.
      console.log('Failed to login. Error = ' + error.message);
 });

Voici le code permettant de créer un objet client des services Outlook.

var outlookClient = new Microsoft.OutlookServices.Client('https://outlook.office365.com/api/v1.0', authtoken.getAccessTokenFn('https://outlook.office365.com'));

Voici le code de fabrique AngularJS complet permettant d'exposer l'API O365.

(function () {
    'use strict';
    angular.module('app365').factory('app365api', [app365api]);

    function app365api() {

        var authContext;
        var authtoken;
        var outlookClient;      
        var userName;

        // Login to O365
        function login(callback) {
            if (!authContext) {
                authContext = new O365Auth.Context();
            }

            authContext.getIdToken("https://outlook.office365.com/")
           .then((function (token) {
               // Get auth token
               authtoken = token;
               // Get user name from token object.
               userName = token.givenName + " " + token.familyName;
               // Create Outlook client object.
               outlookClient = new Microsoft.OutlookServices.Client('https://outlook.office365.com/api/v1.0', authtoken.getAccessTokenFn('https://outlook.office365.com'));
               // Callback without parameter to indicate successful sign-in.
               callback();
           }), function (error) {
               // Log sign-in error message.
               console.log('Failed to login. Error = ' + error.message);
               callback(error.message);
           });
        };

        // Logout
        function logout() {
            if (!authContext) {
                authContext = new O365Auth.Context();
            }

            authContext.logOut();
        };

        // Get signed-in user name.
        function getUserName() {
            return userName;
        };

        return {
            login: login,
            logout: logout,
            getUserName: getUserName,        
            exchangeClientObj: function () { return outlookClient; }
        };
    };
})();

Utilisez l'objet client Outlook pour accéder aux services O365, tels que le courrier, le calendrier, les contacts

Vous pouvez utiliser l'objet client Outlook pour effectuer des opérations de lecture et d'écriture relatives au courrier, au calendrier et aux contacts.

Utiliser l'objet client Outlook pour les opérations de lecture du courrier, du calendrier et des contacts

Le code suivant lit tous les e-mails marqués comme étant importants.

// Get all mails flagged as important.
function getImpMails() {
   NProgress.start();
   // Filter to fetch all important mails received after 2000-10-20
   var filterQuery = "Importance eq 'High' and DateTimeReceived gt 2000-10-20";
   outlookClient.me.folders.getFolder("Inbox").fetch()
   .then(function (folder) {
   // Fetch all important mails sorted by DateTimeReceived.
      folder.messages.getMessages().filter(filterQuery).orderBy('Importance,DateTimeReceived desc').fetch()
.then(function (mails) {
// Get current page. Use getNextPage() to fetch next set of mails.
vm.mails = mails.currentPage;
$scope.$apply();
NProgress.done();
}, function (error) {
    console.log("Error encountered while fetching mails. Error: " + error.message);
 });
}, function (error) {
    console.log("Error encountered while fetching inbox folder. Error: " + error.message);
  });
};

Le code suivant lit tous les événements ayant une date de début égale à aujourd'hui.

var filterQuery = 'start gt ' + today.toISOString() + ' and start lt ' + tomorrow.toISOString();
NProgress.start();
// Get events with filter.
outlookClient.me.calendar.events.getEvents().filter(filterQuery).fetch()
.then(function (events) {
// Get current page. Use getNextPage() to fetch next set of events.
    vm.events = events.currentPage;
    $scope.$apply();
    NProgress.done();
});

Le code suivant lit tous les contacts.

function getContacts() {
NProgress.start();

// Fetch all the contacts.
outlookClient.me.contacts.getContacts().fetch()
.then(function (contacts) {
// Get the current page. Use getNextPage() to fetch next set of contacts.
    vm.contacts = contacts.currentPage;
    $scope.$apply();
    NProgress.done();
  });
};

Utiliser l'objet client Outlook pour supprimer du courrier et un événement de calendrier

L'objet client Outlook peut être utilisé pour supprimer du courrier. Pour supprimer du courrier, récupérez l'e-mail à supprimer à l'aide de l'ID de courrier, puis appelez delete() sur l'objet de courrier afin de supprimer le message spécifique.

Notes

delete() supprime définitivement l'e-mail.Pour déplacer l'e-mail vers Éléments supprimés, utilisez move() à la place.

Voici le code permettant de supprimer du courrier.

// Fetch the mail with specified mail id.                    outlookClient.me.folders.getFolder("Inbox").messages.getMessage(mail.id).fetch()
.then(function (mail) {
    // Delete the mail.
    mail.delete()
    .then((function (response) {
         // mail deleted successfully.                
     }), function (error) {                            
         // Log the error message when error is encountered while deleting the mail.
         console.log('fail to delete mail. Error = ' + error.message);
 });

Voici le code permettant de supprimer un événement.

// Fetch event with specified event id.
outlookClient.me.calendar.events.getEvent(event.id).fetch()
.then(function (event) {
    // Delete event.
    event.delete()
    .then((function (response) {                            
     // Refresh event list.
     }).bind(this), function (reason) {
     // Log delete event error.
     console.log('Fail to delete event. Error = ' + reason.message);
});

Utiliser l'objet client Outlook pour créer un contact et un événement de calendrier

L'objet client Outlook peut être utilisé pour créer des contacts, un événement de calendrier et envoyer du courrier.

Voici le code permettant d'ajouter un nouvel événement de calendrier.

// Event body content
var eventBody = new Microsoft.OutlookServices.ItemBody();
eventBody.contentType = Microsoft.OutlookServices.BodyType.HTML;
eventBody.content = $scope.newEvent.body;
// Event attendee.
var attendee = new Microsoft.OutlookServices.Attendee();
// Attendee email address.
var emailAddress = new Microsoft.OutlookServices.EmailAddress();
emailAddress.address = $scope.newEvent.toRecipients;
attendee.emailAddress = emailAddress;
// Event object.
var event = new Microsoft.OutlookServices.Event();
// Event start date.
event.start = new Date($scope.newEvent.start).toISOString();
// Event end date time
event.end = new Date($scope.newEvent.end).toISOString();
// Event subject.
event.subject = $scope.newEvent.subject;
// Event body.
event.body = eventBody;
// Add event attendee.
event.attendees.push(attendee);
// Event location.
event.location = new Microsoft.OutlookServices.Location();
event.location.displayName = 'Sample Location';
// Add event
outlookClient.me.calendar.events.addEvent(event)
.then((function (response) {
// New event created successfully.
})
.bind(this), function (reason) {
// Log the error message encountered while adding the event.
console.log('Fail to add event. Error = ' + reason.message);
});

Voici le code permettant d'ajouter un nouveau contact.

// Contact object
var contact = new Microsoft.OutlookServices.Contact();

// First and last name
contact.givenName = $scope.newContact.firstname;
contact.surname = $scope.newContact.lastname;

// Mobile phone
contact.mobilePhone1 = $scope.newContact.phone;

// Email address
var emailAddress = new Microsoft.OutlookServices.EmailAddress();
emailAddress.address = $scope.newContact.email;
contact.emailAddresses.push(emailAddress);

// Add Contact
outlookClient.me.contacts.addContact(contact)
.then((function (response) {
// Contact added successfully.

})
.bind(this), function (reason) {
// Log the error message when add contact fails.
console.log('Fail to add contact. Error = ' + reason.message);
});

Exécuter l'application

Sélectionnez Android comme système d'exploitation cible, puis déployez-le sur l'émulateur Android ou sur un appareil Android.