2006 Adobe Systems Incorporated. Tutti i diritti riservati. Utilizzo di Adobe Connect Enterprise Web Services Se la presente guida viene distribuita

Transcript

1

2 2006 Adobe Systems Incorporated. Tutti i diritti riservati. Utilizzo di Adobe Connect Enterprise Web Services Se la presente guida viene distribuita con software che include un accordo di licenza per l utente finale, la guida e il software in esso descritto sono concessi in licenza e possono essere usati e copiati solo in conformità ai termini di tale licenza. Ad eccezione di quanto concesso da tale licenza, nessuna parte di questa guida può essere riprodotta, memorizzata in un sistema per il recupero dati o trasmessa in qualsiasi forma o con qualsiasi mezzo, elettronico, meccanico, di registrazione o altro, senza il previo consenso scritto da parte di Adobe Systems Incorporated. Si noti che il contenuto di questa guida è protetto dalle norme sul copyright, anche se non è distribuito con il software comprendente il contratto di licenza per l'utente finale. Il contenuto della presente guida viene fornito solo a scopo informativo, è soggetto a modifica senza preavviso e non deve essere interpretato come un impegno di Adobe Systems Incorporated. Adobe Systems Incorporated non si assume alcuna responsabilità di eventuali errori o imprecisioni eventualmente presenti nella presente guida. Se in un progetto si intende inserire grafica e immagini esistenti, si tenga presente che tali materiali potrebbero essere protetti dalla legge sul copyright. L inserimento non autorizzato di tali materiali nel proprio lavoro potrebbe rappresentare una violazione dei diritti del titolare del copyright. Chiedere pertanto la necessaria autorizzazione prima di procedere. Qualsiasi riferimento a nomi di società nei modelli di esempio è a titolo puramente dimostrativo e non intende fare riferimento a nessuna organizzazione esistente. Adobe, il logo Adobe, Acrobat, Adobe Captivate, Adobe Connect, Adobe Press, Breeze, Flash, Flash Player, PDF e Shockwave sono marchi o marchi registrati di Adobe Systems Incorporated negli Stati Uniti e/o in altri Paesi. JavaScript è un marchio o un marchio registrato di Sun Microsystems, Inc. negli Stati Uniti e in altri Paesi. Tutti gli altri marchi appartengono ai rispettivi proprietari. La cancellazione dell'eco acustico RealDuplex è protetta dal Copyright SPIRIT. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Avviso per gli utenti finali del Governo degli Stati Uniti. Il Software e la Documentazione sono Articoli commerciali, conformemente alla definizione in 48 C.F.R , che consistono in Software per computer commerciale e Documentazione di sofware per computer commerciale, conformente alle espressioni utilizzate in 48 C.F.R o 48 C.F.R , a seconda del caso. In conformità alla norma 48 C.F.R o 48 C.F.R. dal al applicabile, il software commerciale per computer e la documentazione del software commerciale per computer vengono concessi in licenza agli utenti finali degli enti governativi (a) soltanto come articoli commerciali e (b) soltanto con i diritti attribuiti a tutti gli utenti finali, secondo i termini e le condizioni qui indicate. Tutti i diritti non pubblicati sono riservati, ai sensi della legge sul diritto d autore vigente negli Stati Uniti d America. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA , USA. Per gli utenti finali del Governo degli Stati Uniti, Adobe accetta di rispettare tutte le norme sulle pari opportunità applicabili comprese, se pertinenti, le norme dell'executive Order e relativi emendamenti, Sezione 402 del Vietnam Era Veterans Readjustment Assistance Act del 1974 (38 USC 4212) e la sezione 503 del Rehabilitation Act del 1973 e relativi emendamenti e le norme previste in 41 CFR Parti 60-1, 60-60, e La clausola di azione affermativa e le norme contenute nella sentenza precedente saranno incorporate per riferimento.

3 Sommario Prima di iniziare Suggerimenti e formazione Ambiente di sviluppo Novità di questa guida Risorse aggiuntive Convenzioni Capitolo 1: Architettura Flusso di dati Prima chiamata API Capitolo 2: Login e richieste Login da un'applicazione Inviare una richiesta in un documento XML Analizzare una risposta con XPath Analizzare una risposta di errore Logout di un utente Capitolo 3: Concetti base Trovare un principal-id Elencare entità o ospiti Creare utenti Aggiornare utenti Creare campi personalizzati Creare gruppi Trovare gli oggetti SCO Scaricare file Controllare le autorizzazioni Capitolo 4: Riunioni Trovare riunioni Visualizzare riunioni Creare gli URL delle stanze riunioni

4 Creare riunioni Creare riunioni personalizzate Invitare gli utenti alle riunioni Rimuovere utenti dalle riunioni Calcolare l'utilizzo della riunione Ottenere gli archivi delle riunioni Ottenere i risultatati di un sondaggio di una riunione Avviare riunioni con autenticazione esterna Capitolo 5: Formazione Autorizzazioni della libreria Formazione Trovare corsi e programmi Visualizzare la formazione di un utente Iscrivere un utente Iscrivere un numero elevato di utenti Visualizzare le informazioni sul programma Resoconto dei punteggi Capitolo 6: Riferimento alle azioni Azioni nuove e rimosse acl-field-info acl-field-list acl-field-update acl-preference-update common-info custom-fields custom-fields-delete custom-field-update group-membership-update learning-path-info learning-path-update login logout permissions-info permissions-reset permissions-update principal-info principal-list principal-list-by-field principals-delete principal-update Sommario

5 report-active-meetings report-bulk-consolidated-transactions report-bulk-objects report-bulk-questions report-bulk-slide-views report-bulk-users report-course-status report-curriculum-taker report-meeting-attendance report-meeting-concurrent-users report-meeting-sessions report-meeting-summary report-my-courses report-my-events report-my-meetings report-my-training report-quiz-interactions report-quiz-question-answer-distribution report-quiz-question-distribution report-quiz-question-response report-quiz-summary report-quiz-takers report-quotas report-sco-slides report-sco-views report-user-trainings-taken report-user-training-transcripts sco-contents sco-delete sco-expanded-contents sco-info sco-move sco-nav sco-search sco-shortcuts sco-update sco-upload user-accounts user-transcript-update user-update-pwd Sommario 5

6 Capitolo 7: Riferimento al filtro e all'ordinamento filter-definition sort-definition Capitolo 8: Riferimento comune access field icon lang object-type path-type permission-id status attributo status time-zone-id type Appendice A: Un'applicazione di esempio Creare una classe adattatore Eseguire il login dell'utente Inviare richieste XML Analizzare le risposte XML Visualizzare le informazioni sull'utente Elencare le riunioni di un utente Creare e aggiornare riunioni Visualizzare i dettagli sulla riunione Indice Sommario

7 Prima di iniziare Adobe Connect Enterprise Web Services consente alle applicazioni di interagire con Adobe Connect Enterprise Server 6 o Adobe Connect Enterprise Hosted 6. Nella presente guida viene illustrato il modo in cui un'applicazione invia le chiamate API XML a Connect Enterprise e interpreta la risposta XML. È rivolta agli sviluppatori che desiderano creare applicazioni personalizzate per Connect Enterprise o integrarla con un altro sistema, ad esempio un sistema di gestione dell'apprendimento o un servizio di directory LDAP. Prima di utilizzare questa guida è consigliabile apprendere i concetti base del linguaggio XML e dell'uso di HTTP per comunicare con un server da un'applicazione client. Nella presente guida sono inclusi alcuni esempi di codice Java, ma non si presuppone l'utilizzo di un linguaggio o un ambiente specifico. Suggerimenti e formazione Adobe fornisce una vasta gamma di risorse per aiutare gli utenti a conoscere e utilizzare i prodotti Adobe. Adobe Developer Center: esercitazioni, materiale di riferimento, guide alla creazione di script e altre informazioni approfondite. Altre risorse: formazione, libri, forum utenti, certificati sul prodotto e altro. Extra e download: contenuti e software scaricabili. Adobe Developer Center In questa sezione di Adobe.com basata sulla comunità sono disponibili informazioni per utenti esperti, inclusi gli sviluppatori di software e di componenti aggiuntivi. Qui troveranno esercitazioni, SDK, guide alla creazione di script e codice di esempio, nonché forum, feed RSS, seminari online e altre risorse tecniche. 7

8 Altre risorse Per i prodotti Adobe sono disponibili ulteriori fonti di informazione e aiuto. Visitare la sezione Supporto del sito Web di Adobe per ottenere ulteriori informazioni sulle opzioni di supporto tecnico gratuito e a pagamento. Nei siti Web di Adobe U.S.A. e Adobe Giappone, i problemi principali sono elencati in base al prodotto. Seguire il collegamento Formazione per accedere ai libri Adobe Press, alle risorse online, ai video, ai corsi di formazione guidati da un istruttore, ai programmi di certificazione software Adobe e altro ancora. Visitare la sezione Comunità del sito Web di Adobe per trovare forum, blog e altri canali attraverso i quali gli utenti condividono strumenti e informazioni, fanno domande e scoprono come altri utenti sfruttano al meglio il software. I forum utente sono disponibili in inglese, francese, spagnolo, tedesco e giapponese nella pagina Supporto principale del sito Web di Adobe locale. I blog sono pubblicati in numerose lingue straniere. Extra e download Per i contenuti gratuiti e i componenti aggiuntivi, visitare Adobe Studio Exchange, una comunità online dove gli utenti possono scaricare e condividere migliaia di azioni gratuite, plug-in e altri contenuti utilizzabili con i prodotti Adobe. Per visitare Adobe Studio Exchange, andare su Adobe Design Center dalla pagina iniziale del sito Web di Adobe. I download disponibili nel sito Web di Adobe includono aggiornamenti gratuiti, tryout e altro software utile. Inoltre, la sezione relativa ai plug-in di Adobe Store consente di accedere a migliaia di plug-in di sviluppatori di terze parti per l automatizzazione delle attività, la personalizzazione dei flussi di lavoro, la creazione di effetti professionali specializzati e altro ancora. Ambiente di sviluppo Connect Enterprise Web Services consente di utilizzare qualsiasi linguaggio o piattaforma in cui sia possibile inviare e ricevere XML su HTTP per sviluppare applicazioni personalizzate. Ad esempio, è possibile utilizzare Java e la piattaforma J2EE, C#.NET, PHP, un server di portali oppure qualsiasi piattaforma di sviluppo Web. La maggior parte delle applicazioni personalizzate è costituita da portali o applicazioni Web. 8 Prima di iniziare

9 In generale, gli utenti troveranno utili i seguenti strumenti: Una libreria di codice di analisi XML, se il linguaggio di programmazione utilizzato supporta l'analisi XML. Una libreria di codice di gestione dei cookie che facilita la gestione dei cookie di sessione restituiti da Connect Enterprise. Uno strumento per visualizzare le intestazioni di risposta e richiesta HTTP in un browser. Molti di questi strumenti sono disponibili su Internet. Novità di questa guida La sezione della guida per lo sviluppatore ha ora un nuovo formato passo-passo per la descrizione delle sequenze di chiamata necessarie per eseguire determinate attività utilizzando l'api XML. Questi passi possono essere codificati nella propria applicazione. I riferimenti alle API hanno un nuovo formato che documenta i parametri e gli URL di richiesta, oltre a elementi e attributi di risposta, con esempi di richiesta e risposta. Un'applicazione di esempio è stata aggiunta appositamente per questa versione. L'esempio è costituito da un'applicazione Java e JSP eseguibile in qualsiasi server Web o dell'applicazione conforme allo standard J2EE. Si tratta di uno strumento utile per imparare a creare, visualizzare e aggiornare le riunioni di Adobe Acrobat Connect Professional. Denominato firstapp, l'esempio è disponibile nel file firstapp.zip all'interno della cartella documentation/ samples sul CD del prodotto. Le istruzioni relative all'installazione e all'esecuzione dell'applicazione di esempio sono disponibili nel file Leggimi. Risorse aggiuntive Su Internet è possibile trovare numerose risorse utili che forniscono informazioni su Connect Enterprise, nonché sui servizi Web e XML. Connect Enterprise Centro risorse di Connect Enterprise Il centro risorse, disponibile nel sito Web di Adobe, viene aggiornato regolarmente con esercitazioni, simulazioni, informazioni sulle procedure ottimali e link alle procedure. Centro per sviluppatori di Connect Enterprise Gli sviluppatori troveranno utile il Centro per sviluppatori. Esso viene aggiornato regolarmente con esercitazioni e articoli sulla creazione di applicazioni per Connect Enterprise. Risorse aggiuntive 9

10 Centro documentazione di Connect Enterprise Nel Centro documentazione è disponibile tutta la documentazione dei prodotti Connect Enterprise, scaricabile e consultabile. Centro di assistenza di Connect Enterprise Nel Centro di assistenza sono disponibili informazioni aggiornate, comprese le note tecniche, le presentazioni su Connect Enterprise e le informazioni sul programma di assistenza. È inoltre possibile consultare i Forum di assistenza per discussioni tra utenti su argomenti tecnici. Centro di assistenza su licenza di Connect Enterprise Nel Centro di assistenza su licenza sono disponibili documentazione e altre risorse per i clienti che dispongono della licenza di Adobe Connect Enterprise Server 6. Servizi XML e Web Nella sezione Web Services Primer del sito Web Xml.com (xml.com) vengono illustrati i concetti base dei servizi Web. Nella sezione XML Tutorial del sito Web W3Schools (w3schools.com) viene fornita un'introduzione all'uso del linguaggio XML. Nella sezione XPath Tutorial, anch'essa del sito Web W3Schools (w3schools.com), viene descritto XPath che consente di analizzare un documento XML per poterlo utilizzare in un'applicazione. Nella sezione XSLT Tutorial è contenuta la terza esercitazione del sito Web W3Schools (w3schools.com) che illustra come utilizzare le trasformazioni XSL per convertire dati XML in altri formati. La specifica XSL Transformations (XSLT) contenuta nel sito Web W3C (w3.org) è la definizione ufficiale di XSLT elaborata dal comitato responsabile degli standard. La sezione Numeric Representation of Dates and Time contenuta nel sito Web dell'international Organization for Standardization (iso.org) fornisce informazioni su come usare il formato della data e dell'ora previsto dallo standard ISO Nella sezione Date and Time Formats del sito Web W3C (w3.org) è contenuta la definizione ufficiale del formato della data e dell'ora previsto dallo standard ISO Altre risorse Nel Centro per sviluppatori di Flash Player e in quello per sviluppatori di Flash Media Server, entrambi disponibili nel Centro per sviluppatori di Adobe, sono disponibili articoli, esempi e suggerimenti per lo sviluppo di applicazioni che utilizzano Adobe Flash Player e Adobe Flash Media Server. 10 Prima di iniziare

11 Nella sezione SCORM Concepts del sito Web Eduworks Corporation (eduworks.com) è contenuta un'esercitazione sul modello SCORM (Shareable Content Object Reference Model), sugli oggetti SCO (Shareable Content Objects) e sui sistemi LMS (Learning Management Systems). Nella sezione LDAP Roadmap del sito Web Kings Mountain Systems ( viene presentato il protocollo LDAP (Lightweight Directory Access Protocol). Questo sito mette a disposizione buon materiale di supporto o link per gli sviluppatori che integrano una directory LDAP a Connect Enterprise. Microsoft SQL Server Connect Enterprise è basato su un database Microsoft SQL Server dal quale le applicazioni personalizzate recuperano i dati e sul quale li scrivono. È possibile trovare risorse utili nel Centro per sviluppatori di Microsoft SQL Server (msdn.microsoft.com), incluse informazioni, riferimenti, comunità e supporto. Convenzioni Nella presente guida vengono utilizzate le convenzioni standard del settore per la visualizzazione del codice. Tuttavia, con "riferimento alle API" si indica una definizione formale del contratto API tra un'applicazione chiamante e il server. Di conseguenza, è necessario descrivere le definizioni della sintassi degli URL di richiesta. Sono state inserire sezioni distinte di un'url di richiesta su righe separate, per una maggiore leggibilità, nel modo seguente: &filter-definition=value &session=breezesessioncookievalue Quando si immette un URL di richiesta nella barra degli indirizzi di un browser oppure quando lo si costruisce in un'applicazione, immetterlo o costruirlo su un'unica riga: Gli elementi di sintassi con codice in caratteri blu rappresentano le definizioni costruite, con un collegamento ipertestuale alla sintassi della definizione. Convenzioni 11

12 12 Prima di iniziare

13 CAPITOLO 1 Architettura 1 Benvenuti in Adobe Connect Enterprise Web Services, il livello di servizi Web su Adobe Connect Enterprise Server 6, Adobe Connect Enterprise Hosted 6 e la suite di applicazioni Connect Enterprise. Web Services consente di creare portali o applicazioni Web che integrano le funzionalità di Connect Enterprise e le informazioni di reporting con sistemi di altri produttori quali portali, sistemi di gestione dei rapporti con i clienti e sistemi di pianificazione delle risorse aziendali. Formazione Eventi Relatore Riunione APIs & SDKs Enterprise Server o Enterprise Hosted Tramite un'api XML, Connect Enterprise Web Services fornisce alle applicazioni funzionalità di riunione, formazione ed eventi. Un esempio potrebbe essere dato da un sistema di gestione degli utenti centrale, come una directory LDAP, Microsoft Active Directory o un sistema di un altro produttore che è parte integrante dei processi aziendali. 13

14 Utilizzando Web Services è possibile scrivere un'applicazione in grado di sincronizzare gli utenti tra il sistema e Connect Enterprise. Basando tale applicazione sulla piattaforma J2EE o un'altra tecnologia a scelta, è possibile estrarre un elenco di utenti dalla directory, confrontarlo con un elenco di utenti di Connect Enterprise e quindi eseguire gli aggiornamenti richiesti nel repository utenti di Connect Enterprise, come l'aggiunta o l'eliminazione di utenti o gruppi. Questo non è che un esempio di applicazione personalizzata. Per ulteriori informazioni, visitare il Centro per sviluppatori di Connect Enterprise. Flusso di dati I flussi di dati tra le applicazioni client e Connect Enterprise sono illustrati nel seguente diagramma. Le applicazioni personalizzate scritte dall'utente seguono i percorsi da 1 a 2 e da A a B. Le applicazioni Connect Enterprise, come Adobe Acrobat Connect Professional, Connect Training o Connect Events, possono seguire un qualsiasi percorso di flussi di dati. ` APPLICAZIONE CLIENT CONNECT ENTERPRISE Browser Web 1 A C RTMPS:443 Autorità di certificazione 2 B D API Web Services Server Web/ applicazione Lettore Flash 3 RTMP: Flash Media Server 3a RTMPT:80 4a Database SQL Il flusso di dati tra Connect Enterprise e le applicazioni client Il flusso di dati può essere cifrato con SSL oppure non cifrato. 14 Capitolo 1: Architettura

15 Non cifrato Se il flusso di dati non è cifrato, le connessioni vengono effettuate sui protocolli HTTP e RTMP (Adobe Real Time Messaging Protocol) e seguono i percorsi descritti nella tabella seguente. 1 Il browser Web client richiede una riunione di Acrobat Connect Professional o un URL di contenuto sulla porta (i percorsi della connessione possono variare). 2 Il server Web risponde con un trasferimento di contenuto oppure fornisce al browser client le informazioni per accedere a Acrobat Connect Professional. 3 Adobe Flash Player richiede una connessione ad Adobe Macromedia Flash Media Server su RTMP:1935 e 4 Flash Media Server risponde e viene aperta una connessione permanente per inviare al browser il traffico della riunione. 3a (alternativo) 4a (alternativo) In alcuni casi, Flash Player richiede una connessione a Flash Media Server, ma può ottenere solo una connessione tunnel su RTMPT:80. Flash Media Server risponde e viene aperta una connessione tunnel per inviare al browser il traffico della riunione. Cifrato Se il flusso di dati è cifrato, le connessioni vengono effettuate con sicurezza sui protocolli HTTPS e RTMPS (Real Time Messaging Protocol su SSL), nel modo seguente. A B C D Il browser Web client richiede una riunione sicura o un URL di contenuto su una connessione cifrata su (i percorsi della connessione possono variare). Il server dell'applicazione/web risponde con un trasferimento di contenuto cifrato oppure fornisce al client le informazioni per creare una connessione cifrata su Acrobat Connect Professional. Flash Player richiede una connessione cifrata a Flash Media Server su RTMPS:443. Flash Media Server risponde e viene aperta una connessione permanente per inviare al browser il traffico della riunione. Applicazioni personalizzate Connect Enterprise Web Services fornisce un'api XML, pertanto l'applicazione deve essere in grado di comunicare con Enterprise Server o Enterprise Hosted utilizzando XML su HTTP o XML su HTTPS. L'API viene chiamata dall'applicazione tramite un URL di richiesta e trasmettendo uno o più parametri come coppie nome/valore o documento XML. Dalla risposta XML restituita è possibile estrarre valori. Flusso di dati 15

16 I metadati, inclusi i nomi e le ore delle riunioni o dei corsi, gli URL delle stanze riunioni, gli URL dei contenuti e le informazioni dei rapporti, vengono recuperati dalle applicazioni personalizzate dal database Connect Enterprise. Il flusso di dati per un'applicazione personalizzata che recupera i metadati dal database va da un browser Web client al server dell'applicazione Web client, all'api XML, al server dell'applicazione Web Connect Enterprise e al database SQL e quindi torna indietro. Il flusso di dati tra un'applicazione personalizzata e Connect Enterprise funziona nel modo seguente: 1. Un utente accede all'applicazione personalizzata da un browser Web. 2. L'applicazione chiama l'api XML su o 3. Il server dell'applicazione Web Connect Enterprise autorizza l'applicazione e i suoi utenti, recupera i metadati dal database SQL e restituisce i metadati. 4. Sul lato client, il server Web o dell'applicazione, l'analizzatore XML e le librerie di software gestiscono la risposta e la rimandano all'applicazione. 5. L'utente continua a lavorare nell'applicazione personalizzata e fa clic sull'url di una riunione di contenuto. A questo punto, l'utente accede a un'applicazione Connect Enterprise come Acrobat Connect Professional per entrare in una stanza riunioni e il flusso di dati tipico tra un'applicazione Connect Enterprise e il server ha inizio. Applicazioni Connect Enterprise Le applicazioni Connect Enterprise chiamano il server utilizzando la stessa API XML di Web Services utilizzata da un'applicazione personalizzata. In generale, il contenuto viene trasportato sulla porta HTTP 80 o HTTPS 443. Per contenuto si intende diapositive, pagine HTTP, file Adobe Macromedia Flash (SWF) e file trasferiti mediante il contenitore FileShare. Questi sono i numeri di porta predefiniti configurabili. Per ulteriori informazioni, consultare la Guida all'installazione e alla configurazione di Connect Enterprise. Le comunicazioni trasmesse in streaming in tempo reale provenienti da Flash Media Server vengono trasportate sulla porta RTMP Le comunicazioni trasmesse in streaming includono audio, video (webcam e FLV), condivisione di file e chat. Lo stato della riunione viene anche mantenuto sulla porta RTMP Capitolo 1: Architettura

17 Componenti di Connect Enterprise Sia Enterprise Server sia Enterprise Hosted presentano due componenti server e ciascun server utilizza un database SQL. Il server dell'applicazione Web Il server dell'applicazione Web è il cervello di Connect Enterprise. In esso è contenuta ed eseguita tutta la logica aziendale necessaria per fornire il contenuto agli utenti. Vengono inoltre gestiti il controllo dell'accesso, la sicurezza, le quote e le licenze, nonché le funzioni di gestione come clustering, failover e replica. Nel server dell'applicazione Web viene inoltre gestito Connect Enterprise Manager, l'applicazione attraverso la quale è possibile visualizzare e gestire il contenuto e gli utenti dell'organizzazione, quando non si utilizza un'applicazione personalizzata o un sistema integrato di altri produttori. I metadati che descrivono il contenuto e gli utenti possono essere memorizzati in database SQL replicati singoli o multipli. Il server dell'applicazione Web è "senza stato", ovvero il ridimensionamento è quasi lineare. Flash Media Server Flash Media Server è il motore di Connect Enterprise, consente di trasmettere in streaming l'audio, il video e il contenuto multimediale utilizzando RTMP. Quando una riunione viene registrata e riprodotta, l'audio e il video vengono sincronizzati, oppure il contenuto viene convertito e impacchettato per la condivisione schermo in tempo reale, grazie a Flash Media Server. Flash Media Server gioca inoltre un ruolo fondamentale nella riduzione del carico del server in quanto consente la memorizzazione nella cache delle pagine Web aperte di frequente, dei flussi e dei dati condivisi. Il database SQL Connect Enterprise utilizza il database Microsoft SQL Server per la memorizzazione permanente di metadati di transazione e di applicazioni, comprese informazioni su utenti, gruppi, contenuto e rapporti. I metadati memorizzati nel database vengono recuperati dall'api XML. Il database può essere implementato con Microsoft SQL Server Desktop Engine (MSDE) o la versione completa di Microsoft SQL Server Prima chiamata API Connect Enterprise Web Services presenta una struttura servlet per gestire le richieste API XML. Nel diagramma del flusso di dati, la struttura servlet è rappresentata dal componente API. Il servlet API riceve le richieste XML provenienti dai client e restituisce le risposte XML provenienti dal server dell'applicazione Web e dal database. Prima chiamata API 17

18 Una richiesta all'api XML viene formattata come URL di richiesta HTTP gestito dal servlet API. Un URL di richiesta contiene un nome di azione e parametri in coppie nome/valore, nel modo seguente: Se si dispone dell'accesso a un account Enterprise Server o Enterprise Hosted in cui provare le chiamate API, è possibile fare delle prove. Adobe consiglia di provare le chiamate API nel browser mentre si impara l'api e si scrivono le applicazioni. Prima di iniziare è utile installare uno strumento che consenta di visualizzare le intestazioni di richiesta e risposta HTTP nel browser. Chiamata common-info in un browser 1. (Facoltativo) Attivare uno strumento per visualizzare le intestazioni HTTP nel browser. 2. Aprire un browser e passare alla pagina di login di Connect Enterprise. 3. Senza eseguire il login, eliminare la parte dell'url dopo il nome del dominio e aggiungere una chiamata a common-info: La risposta proveniente da common-info fornisce informazioni sulla sessione con il server, specialmente il cookie che identifica la sessione: <?xml version="1.0" encoding="utf-8"?> <results> <status code="ok" /> <common locale="en" time-zone-id="85"> <cookie>breezbryf9ur23mbokzs8</cookie> <date> t19:02: :00</date> <host> <local-host>abc123def789</local-host> <url>/api/xml?action=common-info</url> <version>breeze_530_r212</version> <user-agent> Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;.NET CLR ) </user-agent> </common> </results> Quando si esegue il login di un utente da un'applicazione, è necessario reinviare il valore del cookie al server per identificare la sessione dell'utente (consultare Login da un'applicazione ). 18 Capitolo 1: Architettura

19 Chiamata principal-list in un browser Il valore del cookie BREEZESESSION ricevuto da common-info viene aggiunto dal browser all'intestazione della richiesta nella richiesta successiva. 1. In un browser web, eseguire il login a Connect Enterprise. Modificare l'url del browser per chiamare principal-list: 2. Controllare l'intestazione della richiesta. Il valore del cookie BREEZESESSION viene reinviato al server: GET /api/xml?action=principal-list HTTP/1.1 Accept: */* Accept-Language: en-us Accept-Encoding: gzip, deflate User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1;.NET CLR ) Host: example.com Connection: Keep-Alive Cookie: BREEZESESSION=breezbryf9ur23mbokzs8 3. Controllare la risposta che elenca tutti i valori "principal" sul server, ciascuno nel proprio elemento principal. <?xml version="1.0" encoding="utf-8"?> <results> <status code="ok" /> <principal-list> <principal principal-id="624526" account-id="624520" type="user" has-children="false" is-primary="false" is-hidden="false"> <name>joe harrison</name> <login>jharrison@example.com</login> < >jharrison@example.com</ > </principal> <principal principal-id="624550" account-id="624520" type="user" has-children="false" is-primary="false" is-hidden="false"> <name>bob jones</name> <login>bjones@example.com</login> < >bjones@example.com</ > </principal>... </principal-list> </results> Aggiungere filtri e ordinamenti Molte azioni nell'api consentono di aggiungere un filtro per restituire solo determinati elementi di risposta o un ordinamento per visualizzare gli elementi di risposta in un determinato ordine. Prima chiamata API 19

20 Un filtro è un parametro speciale che inizia con la parola chiave filter, seguita da un modificatore facoltativo, quindi da un nome di campo e da un valore. Di seguito sono riportati alcuni esempi di filtri: filter-name=jazz doe (che corrisponde ai risultati con il nome esatto jazz doe) filter-like-name=jazz (che corrisponde ai risultati che contengono jazz nel nome) filter-out-type=user (che restituisce i risultati che non hanno un tipo di user) Questi sono solo alcuni tipi di filtri. È possibile trovarne altri in filter-definition. Controllare un'azione nel riferimento (nel Capitolo 6, Riferimento alle azioni ) per verificare che la relativa risposta possa essere filtrata. In generale, se un'azione consente i filtri, è possibile utilizzarli su qualsiasi elemento o attributo di risposta. Un ordinamento è un altro parametro speciale che inizia con la parola chiave sort (o sort1 o sort2), seguita da un nome di campo e quindi da una delle parole chiave asc o desc, ad esempio: sort-name=asc (per ordinare in ordine crescente per name) sort-group-id=desc (per ordinare in ordine decrescente per group-id) Questi sono solo alcuni esempi di ordinamento. È possibile provare gli ordinamenti nel browser oppure consultare sort-definition per ulteriori informazioni. Eseguire una chiamata con un filtro e un ordinamento 1. Chiamare di nuovo principal-list, visualizzando solo i gruppi e ordinandoli alfabeticamente per nome: &sort-name=asc 2. Per limitare la risposta, scegliere un gruppo dall'elenco e filtrare in base al nome: Questa volta viene restituito solo un gruppo: <?xml version="1.0" encoding="utf-8"?> <results> <status code="ok" /> <principal-list> <principal principal-id=" " account-id="624520" type="group" has-children="true" is-primary="false" is-hidden="false"> <name>developers</name> <login>developers</login> </principal> </principal-list> </results> 20 Capitolo 1: Architettura

21 Come procedere partendo da qui A questo punto, è possibile continuare a provare le chiamate nel browser e a osservarne il funzionamento. È la cosa migliore e più facile per imparare l'api XML. Per ulteriori informazioni, consultare una di queste fonti: I riferimenti alle API nel Capitolo 6, Riferimento alle azioni Il Capitolo 2, Login e richieste, per informazioni su come eseguire il login degli utenti dalle applicazioni. Il Capitolo 3, Concetti base, per imparare i tre concetti base sulle API. Il Capitolo 4, Riunioni, per creare e gestire riunioni da un'applicazione. Il Capitolo 5, Formazione, per creare un'applicazione per la formazione. Prima chiamata API 21

22 22 Capitolo 1: Architettura

23 CAPITOLO 2 Login e richieste 2 In questo capitolo viene illustrato come eseguire il login di un utente dall'applicazione, effettuare richieste, gestire le risposte ed eseguire il logout. Sono disponibili vari modi per eseguire la maggior parte di queste attività, a seconda dell'ambiente di sviluppo, della configurazione del server e della progettazione dell'applicazione. Login da un'applicazione Qualsiasi applicazione personalizzata scritta che utilizzi la funzionalità Adobe Connect Enterprise Web Services o si integri a un sistema di un altro produttore deve eseguire il login di un utente ad Adobe Connect Enterprise Server 6 o a un account di Adobe Connect Enterprise Hosted 6. Nella sua forma più semplice, il processo di login prevede la chiamata dell'azione login. Tuttavia, la tecnica di login varia a seconda che si utilizzi la gestione dei cookie, che si disponga di un server con licenza o di un account su host e che si effettui l'autenticazione direttamente in Connect Enterprise o si utilizzi un'autenticazione esterna. A seconda dell'ambiente e della configurazione del server, è possibile utilizzare combinazioni di queste opzioni. Gestione dei cookie Quando un utente effettua il login, Connect Enterprise restituisce un cookie che identifica la sessione dell'utente. È necessario ritrasmettere il cookie al server su tutte le chiamate effettuate al server durante la sessione dell'utente. Quando l'utente si disconnette, il server fa scadere il cookie che viene quindi invalidato. Nell'ambiente di sviluppo, è possibile utilizzare una libreria di codici che gestisca automaticamente i cookie. Il processo di login e gestione di una sessione dell'utente varia a seconda che si utilizzi una libreria di gestione dei cookie o si gestisca da soli la sessione dell'utente. 23

24 Server con licenza o account su host Sia che l'organizzazione disponga di Enterprise Server con licenza all'interno del firewall o di un account Enterprise Hosted presso Adobe, le richieste XML vengono inviate su HTTP o HTTPS. I requisiti di sicurezza e il processo di login, invece, variano. I clienti su host possono utilizzare determinati parametri con l'azione login per evitare di inviare ID e password degli utenti su Internet. Autenticazione diretta o esterna Tanto per i clienti su host quanto per quelli con licenza, l'autenticazione dell'applicazione potrebbe avvenire direttamente su Connect Enterprise. In alternativa, è possibile autenticare gli utenti sulla propria rete, impostare un identificatore in un'intestazione di richiesta HTTP e inviarla a Connect Enterprise. Il processo di login varia a seconda che si utilizzi o meno l'autenticazione diretta o esterna. Login a Enterprise Server La tecnica standard per eseguire il login di un utente a Enterprise Server prevede l'utilizzo dell'azione login, con trasmissione dell'id e della password di login dell'utente. Questa tecnica funziona sia con le richieste HTTP GET sia POST. È inoltre necessario gestire il cookie BREEZESESSION restituito dal server per ciascuna sessione dell'utente. Se si utilizza una libreria di gestione dei cookie lato client, è preferibile optare per la gestione automatica dei cookie, anziché quella manuale. Se non si dispone di una libreria di questo tipo, chiamare login con il parametro session, in quanto è molto più facile e affidabile rispetto all'impostazione dei valori delle intestazioni HTTP. NOTA Se si invia la password dell'utente a Enterprise Server, usare SSL in modo che venga cifrata durante il transito, anche se si dispone di un Enterprise Server con licenza all'interno del proprio firewall. Eseguire il login con la gestione dei cookie 1. Chiamare l'azione login, trasmettere l'id e la password di login dell'utente, ma non immettere il parametro session: &password=football 2. Analizzare la risposta per un codice di stato ok. Se il login ha esito positivo, il cookie BREEZESESSION viene restituito nell'intestazione della risposta: Set-Cookie: BREEZESESSION=breezbryf9ur23mbokzs8;domain=.macromedia.com;path=/ 3. Optare per la gestione automatica del cookie BREEZESESSION tramite la libreria di gestione dei cookie. 24 Capitolo 2: Login e richieste

25 La libreria lato client ritrasmette il cookie al server in un'intestazione di richiesta nelle chiamate successive per il resto della sessione dell'utente. Non è necessario impostare esplicitamente il cookie nell'intestazione della richiesta. Quando l'utente si disconnette il cookie scade. Eseguire il login utilizzando il parametro della sessione 1. Prima di eseguire il login dell'utente, chiamare common-info per ottenere il valore del cookie BREEZESESSION: 2. Estrarre il valore del cookie dalla risposta: <cookie>breezxq66rt43poai3if8</cookie> 3. Eseguire il login dell'utente, specificando il valore del cookie: &password=football&session=breezxq66rt43poai3if8 4. Analizzare la risposta per un codice di stato ok. 5. Utilizzare il parametro session con lo stesso valore del cookie nelle chiamate successive per l'utente, fino al termine della sessione: &session=breezxq66rt43poai3if8 6. Quando l'utente si disconnette o termina la sessione, non riutilizzare il valore del cookie. Login a Enterprise Hosted Se si desidera eseguire il login direttamente a un account su host o a più account su host, è sempre necessario utilizzare l'azione login, ma occorre specificare un ID account o un nome di dominio, oltre all'id e alla password di login dell'utente. È possibile specificare un nome di dominio qualora si desideri evitare l'invio di un ID account su Internet. Con un account su host non è possibile utilizzare l'autenticazione sign-on o esterna singola. È necessario trasmettere le credenziali di autenticazione dell'utente su Enterprise Hosted, non le credenziali per una rete esterna. NOTA Poiché si inviano ID utente, password e informazioni sull'account su Internet al proprio account sull'host Adobe, è importante che SSL sia attivato sull'account Enterprise Hosted. Login da un'applicazione 25

26 Login a Enterprise Hosted con un ID account 1. Prima di eseguire il login dell'utente, chiamare common-info con il nome di dominio dell'account su host nell'url di richiesta o nel parametro domain: Analizzare la risposta per i valori di cookie e account-id: <cookie>sbreezzd2dfr2ua5gscogv</cookie>... <account account-id="295153" /> 3. Ottenere l'id e la password di login dell'utente nell'applicazione. 4. Chiamare l'azione login, aggiungendo le credenziali dell'utente e i parametri account-id e session: &password=happy&account-id=295153&session=sbreezzd2dfr2ua5gscogv 5. Analizzare la risposta per un codice di stato ok. 6. (Facoltativo) Se si preferisce, è possibile chiamare login prima di common-info, estrarre il valore del cookie dall'intestazione della risposta e gestirlo manualmente o tramite una libreria di gestione dei cookie. Per ulteriori informazioni, consultare Eseguire il login con la gestione dei cookie o Eseguire il login utilizzando il parametro della sessione. Login a Enterprise Hosted con un nome di dominio 1. Prima di eseguire il login dell'utente, chiamare common-info con il nome di dominio dell'account su host nell'url di richiesta o nel parametro domain: Analizzare la risposta per verificare la presenza dei valori di cookie e host: <cookie>breezxq66rt43poai3if8</cookie>... <host> 3. Estrarre il nome di dominio dal valore di host: acme.adobe.com 4. Nell'applicazione, ottenere l'id e la password di login dell'utente. Assicurarsi che l'id di login sia l'id di login di Enterprise Hosted dell'utente, non uno esterno. 26 Capitolo 2: Login e richieste

27 5. Chiamare login, aggiungendo le credenziali dell'utente e i parametri domain e session: &password=smith99&domain=acme.adobe.com&session=breezxq66rt43poai3if8 domain è equivalente a account-id, ma utilizzandolo è possibile evitare di inviare un ID account su Internet, specialmente se si utilizza una connessione non cifrata. 6. Analizzare la risposta per verificare la presenza di un codice di stato di ok. 7. (Facoltativo) Se si preferisce, è possibile chiamare login prima di common-info, estrarre il valore del cookie dall'intestazione della risposta e gestirlo manualmente o tramite una libreria di gestione dei cookie. Per ulteriori informazioni, consultare Eseguire il login con la gestione dei cookie o Eseguire il login utilizzando il parametro della sessione. Login tramite l'autenticazione dell'intestazione HTTP NOTA Le istruzioni fornite in questa sezione sono applicabili solo a Enterprise Server. L'applicazione può utilizzare un server centrale affidabile per autenticare gli utenti con sign-on singolo e trasmettere l'autenticazione della rete (qui definita esterna) a Enterprise Server, senza trasmettere esplicitamente un ID e una password utente di Enterprise Server. (Per istruzioni dettagliate su come impostare e configurare l'autenticazione dell'intestazione HTTP, consultare la Guida all'installazione e alla configurazione di Adobe Connect Enterprise). Login da un'applicazione 27

28 Con l'autenticazione dell'intestazione HTTP, un utente esegue il login al server di autenticazione. Dopo che l'utente si è autenticato, è necessario aggiungere un'intestazione di richiesta HTTP che identifichi l'utente oppure configurare un server proxy per aggiungere l'intestazione. Il filtro di autenticazione in Connect Enterprise (denominato HeaderAuthenticationFilter) converte l'identificatore dell'utente in un ID di login di Connect Enterprise e autentica l'utente. Server di autenticazione Server proxy Connect Enterprise Server Filtro di autenticazione Esterno Esterno con intestazione Enterprise Server Database SQL I filtri di autenticazione convertono le credenziali di autenticazione esterna in credenziali di Enterprise Server. L'autenticazione esterna funziona in aggiunta all'autenticazione standard di Connect Enterprise. Ogni utente che deve accedere a Enterprise Server deve disporre di un login e di una password di Enterprise Server validi. Quando si invia una richiesta di login a Enterprise Server con una credenziale di autenticazione esterna: Il filtro di autenticazione intercetta la richiesta e verifica la presenza di un utente su Enterprise Server con un campo ext-login corrispondente alla credenziale esterna. Se esiste una corrispondenza, il filtro trasmette l'autenticazione esterna a Enterprise Server e il server esegue il login dell'utente. Se non esiste una corrispondenza, il filtro trasmette al server la richiesta di login che visualizza la relativa pagina. L'utente deve quindi eseguire il login a Enterprise Server. Se il login dell'utente ha esito positivo, Enterprise Server aggiorna il campo ext-login nel profilo dell'utente con la credenziale esterna proveniente dalla richiesta. Al successivo invio di una richiesta con la credenziale esterna dell'utente, Enterprise Server trova una corrispondenza in ext-login e l'utente non deve effettuare il login a Connect Enterprise. Se il login dell'utente ha esito negativo, non può accedere alle applicazioni, al contenuto o alle riunioni di Enterprise Server. Nelle procedure seguenti viene descritto come chiamare login quando si utilizza l'autenticazione dell'intestazione HTTP. 28 Capitolo 2: Login e richieste