MaketRandevu/doc/Google Calendar API/google-calendar-api.tex

%% =============================
%% GENERAL SETTINGS
%% =============================
\documentclass[12pt]{article}

\usepackage [margin=2.5cm]{geometry}
\usepackage {graphics}
\usepackage {xltxtra} 
\usepackage {xgreek} 
\usepackage {color}
\usepackage {hyperref}
\hypersetup {colorlinks}


\setmainfont[Mapping=tex-text]{Tahoma} 
\setlength{\parindent}{0cm} 				%% No paragraph indent

\definecolor{darkred}{rgb}{0.5,0,0}
\definecolor{darkgreen}{rgb}{0,0.5,0}
\definecolor{darkblue}{rgb}{0,0,0.5}

\hypersetup{ colorlinks,
linkcolor=darkblue,
filecolor=darkgreen,
urlcolor=darkblue,
citecolor=darkred }

%% =============================
%% DOCUMENT PROPERTIES
%% =============================
\title{{\Huge {\bf Easy!Appointments}} \\[0.3cm] Google Calendar API}
\author{Αλέξανδρος Τσελεγγίδης}
\date{Απρίλιος 2013}

%% =============================
%% DOCUMENT CONTENT
%% =============================
\begin{document}
\maketitle 
\thispagestyle{empty} %% Απομάκρυνση page number από την πρώτη σελίδα

%% ΕΙΣΑΓΩΓΗ ΣΤΟ API
\section {Εισαγωγή}
Το Ημερολόγιο της Google είναι μια διαδικτυακή εφαρμογή που επιτρέπει στους χρήστες της να κρατάνε τα ραντεβού και τα συμβάντα τους σε ένα όμορφο περιβάλλον. Εκτός αυτού υπάρχουν πολλές πρόσθετες δυνατότητες όπως ο συγχρονισμός ημερολογίου με κάποια άλλη εφαρμογή ή η κοινή χρήση ενός ημερολογίου από πολλά άτομα.
\\[0.3cm]
Όπως και με τα περισσότερα προϊόντα της Google παρέχονται εργαλεία με τα οποία μπορούν οι προγραμματιστές να επικοινωνήσουν και να λάβουν δεδομένα από τις υπηρεσίες της εταιρείας. Με αυτόν τον τρόπο είναι δυνατή η ανάπτυξη εφαρμογών οι οποίες διαχειρίζονται αυτά τα δεδομένα.
\\[0.3cm]
Το Google Calendar API (Application Programming Interface) είναι μια πλατφόρμα διαχείρισης συμβάντων ενός ημερολογίου από την Google. Επιτρέπει στον προγραμματιστή να πραγματοποιήσει λειτουργίες προσθήκης, επεξεργασίας, διαγραφής και αναζήτησης συμβάντων μέσω ενός RESTful στυλ κλήσεων προς τον server.
\\[0.3cm]
Με την έννοια RESTful (Representional State Transfer)  εννοείται ένας από τους πιο δημοφιλής τρόπους επικοινωνίας στον παγκόσμιο ιστό. Η επικοινωνία γίνεται με την χρήση ειδικών αιτήσεων προς τους servers, οι οποίοι με την σειρά τους είναι σε θέση να τις επεξεργαστούν και να επιστρέψουν δεδομένα πίσω στον client. Οι μέθοδοι αιτήσεων που είναι διαθέσιμες είναι:
\begin{enumerate}
\item GET
\item POST
\item PUT
\item DELETE
\end{enumerate}

Το API μπορεί να χρησιμοποιηθεί από διάφορες γλώσσες (PHP, Java, .NET, Ruby κτλ) χάρη στις βιβλιοθήκες που παρέχει η Google προς χρήση. Έτσι διευκολύνεται πολύ η διαδικασία ανάπτυξης μιας εφαρμογής που βασίζεται πάνω σε αυτήν την υπηρεσία.
\\[0.3cm]
Για να αποτρέψει η Google την υπερβολική χρήση της υπηρεσίας Calendar, έχει θέσει ένα υπέρτατο όριο 10.000 request την ημέρα. Αν κάποια εταιρεία ξεπεράσει αυτό το όριο τότε θα χρειαστεί να πληρώσει κάποιο αντίτιμο για να μπορέσει να συνεχίσει κανονικά την χρήση.

\section {Περιγραφή Του API}
Το Ημερολόγιο της Google είναι ένα πολύ δυνατό και ευέλικτο εργαλείο. Οι χρήστες μπορούν να βλέπουν το ίδιο ημερολόγιο σε οποιαδήποτε συσκευή βρίσκονται έχοντας απλώς σύνδεση με το διαδίκτυο για να μπορέσει να εκτελεστεί η διαδικασία του συγχρονισμού. Όλες οι εφαρμογές αυτές χρησιμοποιούν το API για να υλοποιήσουν τις βασικές λειτουργίες ενός ημερολογίου, δηλαδή την διαχείριση και την εύκολη εύρεση συμβάντων. Αφού γίνουν οι αλλαγές αυτές θα χρειαστεί να συγχρονιστεί το ημερολόγιο με το διαδίκτυο έτσι ώστε να είναι διαθέσιμο και στις υπόλοιπες συσκευές. 
\\[0.3cm]
Στην ευρεία χρήση της υπηρεσίας συντελεί το ότι η πλατφόρμα του ημερολογίου είναι συμβατή με διάφορες γλώσσες προγραμματισμού και έτσι μπορεί να υλοποιηθούν εφαρμογές για όλες τις συσκευές με ανεπτυγμένο λειτουργικό σύστημα.
\\[0.3cm]
Οι βασικές έννοιες του συστήματος ενός ημερολογίου είναι:

\begin{itemize}
\item Συμβάν (Event) - αντιπροσωπεύει ένα συμβάν στο ημερολόγιο το οποίο έχει τίτλο, περιγραφή, 
ημερομηνία και συμμετέχοντες. 

\item Ημερολόγιο (Calendar) - αντιπροσωπεύει ένα ημερολόγιο το οποίο περιέχει πολλά συμβάντα. Ένας χρήστης μπορεί να έχει πολλά ημερολόγια. Περιέχει επιπλέον πληροφορίες όπως η περιγραφή του ημερολογίου, ο ιδιοκτήτης κτλ.

\item Λίστα Ημερολογίων (Calendar List) - αντιπροσωπεύει μια λίστα με όλα τα ημερολόγια ενός χρήστη της υπηρεσίας αυτής.

\item Ρύθμιση (Setting) - αντιπροσωπεύει μια επιλογή του χρήστη, η οποία επηρεάζει τον τρόπο λειτουργίας της υπηρεσίας (πχ ρύθμιση ζώνης ώρας).

\item ACL (Access Control Rule) - αντιπροσωπεύει έναν κανόνα πρόσβασης του ημερολογίου (όπως παραδείγματος χάρη το αν το ημερολόγιο είναι δημόσιο ή ιδιωτικό).

\item Χρώμα (Color) - αντιπροσωπεύει το χρώμα για κάποια στοιχεία στο περιβάλλον χρήστη της εφαρμογής και τα συμβάντα.

\item Ελεύθερος / Απασχολημένος (Free / Busy) - αντιπροσωπεύει μια χρονική περίοδο στο ημερολόγιο όπου ο χρήστης είναι είτε απασχολημένος είτε ελεύθερος. Αν είναι απασχολημένος δεν μπορούν να υπάρχουν συμβάντα σε αυτό το διάστημα.
\end{itemize}

Το API της Google λειτουργεί με “resources” και “collections” για να χειριστεί τις προαναφερθέντες έννοιες. Ένα resource αντιπροσωπεύει μια συγκεκριμένη οντότητα η οποία περιέχει δεδομένα για την εφαρμογή. Πολλά resource μαζί απαρτίζουν ένα collection το οποίο περιέχει πολλές χρήσιμες μεθόδους μαζικής διαχείρισης δεδομένων.
\\[0.3cm]
Οι προγραμματιστές διαμορφώνουν τον κωδικά τους έτσι ώστε να είναι συμβατός με αυτήν την δομή και έτσι η επικοινωνία με την υπηρεσία της Google να είναι ευκολότερη. 

\section {Πως χρησιμοποιείται το API}
Η χρήση του API μπορεί να γίνει απευθείας με κλήσεις RESTful προς τον server της Google, είτε με χρήση κάποιων από τις έτοιμες βιβλιοθήκες που παρέχει η εταιρεία. Επίσης είναι απαραίτητη η ύπαρξη ενός λογαριασμού στην Google καθώς και η καταχώρηση του project στο Google API Console έτσι ώστε να πάρει ο προγραμματιστείς ένα API Key, ένα κλειδί το οποίο είναι απαραίτητο για την χρήση της υπηρεσίας. 
\\[0.3cm]
Αν ο προγραμματιστής επιλέξει την χρήση της RESTful μεθόδου επικοινωνίας, θα χρειαστεί αν στέλνει request σε διάφορα URL και έτσι να παίρνει απαντήσεις με τα δεδομένα που χρειάζεται. Όλες οι απαντήσεις είναι σε JSON μορφή οπότε είναι πιθανόν να χρειαστεί να τις αναλύσει (parse) πριν τις χρησιμοποιήσει στην εφαρμογή του. 
\\[0.3cm]
Δείγματα από URL για την κλήση διαφόρων μεθόδων: 

\begin{verbatim}
https://www.googleapis.com/calendar/v3/lists/calendarListID/calendar?parameters
https://www.googleapis.com/calendar/v3/users/userID/lists?parameters
\end{verbatim}

Αντιθέτως με την χρήση των έτοιμων βιβλιοθηκών οι διαδικασίες επικοινωνίας είναι έτοιμες και ο προγραμματιστής μπορεί να πετύχει την επικοινωνία με τους servers της Google γρηγορότερα και ευκολότερα. Υπάρχουν βιβλιοθήκες για την Java, την PHP, την Python, το .NET περιβάλλον και την Ruby και πολλές άλλες γλώσσες και τεχνολογίες. 
\\[0.3cm]
Αφού κατεβάσουμε τις βιβλιοθήκες και τις βάλουμε σε κάποιο σημείο μέσα στο project, μπορούμε να τις χρησιμοποιήσουμε μέσα από τον κώδικα:

\begin{verbatim}
require_once "../src/apiClient.php";
require_once "../src/contrib/apiCalendarService.php";
\end{verbatim}

Στην συνέχεια είναι απαραίτητο να ρυθμίσουμε κάποιες παραμέτρους έτσι ώστε να είμαστε σε θέση να χρησιμοποιήσουμε αυτήν την υπηρεσία:

\begin{verbatim}
global $apiConfig;

$apiConfig = array(
    // Site name to show in Google's OAuth authentication screen
    'site_name' => 'www.example.org',

    // OAuth2 Setting, you can get these keys on the API Access tab on
    // the Google APIs Console
    'oauth2_client_id' => 'YOUR_CLIENT_ID',
    'oauth2_client_secret' => 'YOUR_CLIENT_SECRET',
    'oauth2_redirect_uri' => 'YOUR_REDIRECT_URL',

    // The developer key; you get this from the Google APIs Console
    'developer_key' => 'YOUR_DEVELOPER_KEY',
    ...

    // Which Authentication, Storage and HTTP IO classes to use.
    'authClass' => 'apiOAuth2',
    ....

    // Definition of service specific values like scopes, OAuth token URLs, etc
    'services' => array(
        'calendar' => array('scope' => 'https://www.googleapis.com/auth/calendar'),
    )
);
\end{verbatim}

Έπειτα θα χρειαστεί να γίνει εκκίνηση του service και να ολοκληρωθεί η διαδικασία πιστοποίησης (authenticate) με την χρήση του API Key που αντιστοιχεί στην εφαρμογή.

\begin{verbatim}
<?php
session_start();

require_once "../src/apiClient.php";
require_once "../src/contrib/apiCalendarService.php";

$apiClient = new apiClient();
$apiClient->setUseObjects(true);
$service = new apiCalendarService($apiClient);

if (isset($_SESSION['oauth_access_token'])) {
  $apiClient->setAccessToken($_SESSION['oauth_access_token']);
} else {
  $token = $apiClient->authenticate();
  $_SESSION['oauth_access_token'] = $token;
}
...
\end{verbatim}

Με αυτόν τον τρόπο εκτελούνται οι διαδικασίες ανταλλαγής δεδομένων μεταξύ του Google Calendar και του συστήματος του προγραμματιστή.

\end{document}