Interfaccia SOAP del FUSC/Simap/FUC ZH - Versione 3.0
←
→
Trascrizione del contenuto della pagina
Se il tuo browser non visualizza correttamente la pagina, ti preghiamo di leggere il contenuto della pagina quaggiù
Interfaccia SOAP del FUSC/Simap/FUC ZH
Versione 3.0Indice
1 Introduzione ...................................................................................................... 4
2 Descrizione........................................................................................................ 5
2.1 Condizioni per l’utilizzo del web service .......................................................................... 5
2.2 Il server SOAP................................................................................................................... 5
2.3 Attivazione del web service .............................................................................................. 5
2.3.1 Operazioni ad uso di un foglio ufficiale cantonale ....................................................... 6
2.3.1.1 Operazione getActualCantonNoticeList()...................................................... 6
2.3.1.2 Operazione getActualCantonNoticeListForCategory(category) .................. 6
2.3.1.3 Operazione getNoticeList(publishDate) ........................................................ 6
2.3.2 Operazioni ad uso degli abbonati ................................................................................ 7
2.3.2.1 getNoticeListForSubscriber(publishDate, subscriptionId)............................ 7
2.3.2.2 getNoticeListForSubscriberDateRange(publishDateFrom, publishDateTo,
subscriptionId) ....................................................................................................................... 7
2.3.3 Operazioni di uso generale .......................................................................................... 8
2.3.3.1 getNoticeXml(documentId)............................................................................. 8
2.3.3.2 getNoticePdf(documentId) ............................................................................. 8
2.3.4 getNoticeXmls(publishDate) ....................................................................................... 8
2.3.5 Operazione ad uso del foglio ufficiale del Cantone di Zurigo ....................................... 9
2.4 Messaggi di errore ............................................................................................................ 9
2.5 Esempio di programma in Java ..................................................................................... 10
KPS Documents Interfaccia SOAP del FUSC/Simap/FUC ZH Pagina 2/11Cronologia modifiche
Versione (n.) Data Modifica Pagine Autore
1.0 15.02.2012 Elaborazione Tutte J.Quapp
1.1 10.04.2012 Piccole modifiche e Tutte J.Quapp
esempio di
programma
1.2 24.05.2012 Modifiche di dettagli J.Quapp
2.0 01.10.2012 Ampliamento del Tutte J.Quapp
service
2.01 24.10.2012 Correzioni del testo J.Quapp
3.0 22.11.2012 Correzioni del testo SECO
KPS Documents Interfaccia SOAP del FUSC/Simap/FUC ZH Pagina 3/111 Introduzione Il FUSC e Simap offrono un’interfaccia SOAP per gestire la chiamata delle API. Il presente documento contiene tutte le informazioni necessarie per l’utilizzazione dell’interfaccia SOAP. Se non siete ancora registrati come utenti in FUSC o in Simap, potete farlo cliccando sui link seguenti: https://www.shab.ch/ oppure https://www.simap.ch/ SOAP è un protocollo (basato su http) per l’offerta di web service. Il web service permette di accedere alle funzioni messe a disposizione dal FUSC e da Simap partendo da un altro programma e indipendentemente dal linguaggio di programmazione utilizzato per quest’ultimo. KPS Documents Interfaccia SOAP del FUSC/Simap/FUC ZH Pagina 4/11
2 Descrizione
2.1 Condizioni per l’utilizzo del web service
• L’utente del web service deve essere registrato come utente del FUSC/Simap.
• L’accesso a funzioni speciali richiede la concessione di diritti supplementari
all’utente.
2.2 Il server SOAP
L’accesso al server SOAP avviene mediante gli URL seguenti:
https://www.shab.ch/soapserver oppure https://www.simap.ch/soapserver
2.3 Attivazione del web service
È indispensabile effettuare l’autenticazione nell’header http.
Se con la richiesta della funzione non viene inviata l’autenticazione con l’header http,
in risposta si riceve un messaggio di errore. L’autenticazione nell’header http avviene
mediante i due parametri username (nome utente) e password
(password).
La struttura dell’header http è perciò la seguente:
POST /soapserver HTTP/1.1
username: [NOME UTENTE]
SOAPAction: ""
Accept: text/xml, multipart/related, text/html, image/gif, image/jpeg, *;
q=.2, */*; q=.2
Content-Type: text/xml; charset=utf-8
password: [PASSWORT]
User-Agent: Java/1.6.0_23
Host: www.shab.ch
Connection: keep-alive
Content-Length: 273
Il nome utente e la password sono identici a quelli utilizzati per l’accesso a
FUSC/Simap.
L’utilizzazione del web service può avvenire soltanto dopo l’autenticazione. Vi
rammentiamo che in alcuni casi l’attivazione del web service richiede
un’autorizzazione speciale.
L'autenticazione può essere verificata mediante la funzione getAuthentication.
KPS Documents Interfaccia SOAP del FUSC/Simap/FUC ZH Pagina 5/11Operazioni supportate
Qui di seguito sono descritte tutte le funzioni offerte dal service. Tutte le altre funzioni
sono destinate ad un uso interno e pertanto non sono disponibili.
2.3.1 Operazioni ad uso di un foglio ufficiale cantonale
I fogli ufficiali cantonali possono caricare nel loro sistema redazionale le nuove
comunicazioni mediante le funzioni di cui sotto. Le comunicazioni possono essere
caricate in formato xml.
2.3.1.1 Operazione getActualCantonNoticeList()
Descrizione:
Questa funzione visualizza tutti gli ID delle comunicazioni convalidate e pubblicate,
con data di chiusura redazionale compresa nei 14 giorni che precedono l’avvio della
ricerca.
Sono trasmessi soltanto i dati relativi alle comunicazioni
- il cui stato è «approvato» o «pubblicato»;
- selezionate nel FUSC nella sezione corrispondente a quella scelta al
momento della registrazione dalla tipografia cantonale.
Accessibilità: l’accesso all’operazione è consentito soltanto se lo stato di utente
corrisponde a «tipografia cantonale».
2.3.1.2 Operazione getActualCantonNoticeListForCategory(category)
Argomenti:
- category si tratta della sigla di una rubrica, formata da due segni.
Esempio: «KK»=fallimenti
Descrizione:
Questa funzione visualizza tutti gli ID delle comunicazioni convalidate e pubblicate,
con data di chiusura redazionale compresa nei 14 giorni che precedono l’avvio della
ricerca.
Sono trasmessi soltanto i dati relativi alle comunicazioni:
- il cui stato è «approvato» o «pubblicato»;
- selezionate nel FUSC nella rubrica [category];
[category] può assumere i seguenti valori: «AW»,«KK»,«NA»,«SB»,«HR»;
- in Simap [category] può assumere soltanto il valore «OB»;
Accessibilità: l’accesso all’operazione è consentito soltanto se lo stato di utente
corrisponde a «tipografia cantonale».
2.3.1.3 Operazione getNoticeList(publishDate)
Argomenti:
- publishDate si tratta di una data di pubblicazione.
KPS Documents Interfaccia SOAP del FUSC/Simap/FUC ZH Pagina 6/11Descrizione:
Una tipografia cantonale ottiene tutti gli ID relativi ai documenti oggetto di
comunicazioni con la data di pubblicazione indicata. Sono trasmessi soltanto i dati
relativi alle comunicazioni:
- il cui stato è «approvato» o «pubblicato»;
- selezionate nel FUSC nella rubrica corrispondente a quella scelta al momento
della registrazione da parte della tipografia cantonale.
Accessibilità: l’accesso all’operazione è consentito soltanto se lo stato di utente
corrisponde a «tipografia cantonale».
2.3.2 Operazioni ad uso degli abbonati
Gli abbonati possono ricevere comunicazioni in formato xml anche tramite questo
web service se hanno scelto il formato di dati corrispondente.
2.3.2.1 getNoticeListForSubscriber(publishDate, subscriptionId)
Argomenti:
- publishDate si tratta di una data di pubblicazione del FUSC;
- subscriptionId si tratta dell’ID del vostro abbonamento. L’ID
dell’abbonamento si trova nell‘area clienti abbonamento online – i miei dati
nell’elenco abbonati. Nel caso di abbonamenti rinnovati è sufficiente un ID
qualsiasi.
Descrizione: si ottiene un elenco di ID di comunicazioni. L’elenco viene generato
dalla ricerca avviata dall’abbonato. Le comunicazioni corrispondono a quelle che
l’abbonato vede nella sua area clienti per la data di pubblicazione scelta.
Viene generato un elenco di ID di comunicazioni pubblicate alla data specificata e
rispondenti ai criteri di ricerca definiti dall’abbonato.
Accessibilità: l’accesso all’operazione è consentito soltanto se lo stato di utente
corrisponde a «abbonato FUSC».
2.3.2.2 getNoticeListForSubscriberDateRange(publishDateFrom,
publishDateTo, subscriptionId)
Argomenti:
- publishDateFrom si tratta di una data di pubblicazione del FUSC (a partire
da);
- publishDateTo si tratta di una data di pubblicazione del FUSC (fino a);
- subscriptionId Si tratta dell’ID del vostro abbonamento. L’ID
dell’abbonamento si trova nell‘area clienti abbonamento online – i miei dati
nell’elenco abbonati. nel caso di abbonamenti rinnovati è sufficiente un ID
qualsiasi.
Descrizione: viene trasmesso un elenco di ID di comunicazioni. L’elenco viene
generato dalla ricerca avviata dall’abbonato. Le comunicazioni corrispondono a
quelle che l’abbonato vede nella sua area clienti per l’arco di tempo scelto per la data
di pubblicazione [publishDateFrom]-[ publishDateTo].
KPS Documents Interfaccia SOAP del FUSC/Simap/FUC ZH Pagina 7/11Viene generato un elenco di ID di comunicazioni pubblicate nell’arco di tempo specificato e rispondenti ai criteri di ricerca definiti dall’abbonato. Accessibilità: l’accesso all’operazione è consentito soltanto se lo stato di utente corrisponde a «abbonato FUSC». Vi rammentiamo che occorre inserire sempre l’ID dell’abbonamento in corso. 2.3.3 Operazioni di uso generale Le seguenti operazioni sono accessibili a diversi gruppi di utenti. 2.3.3.1 getNoticeXml(documentId) Argomenti: - documentId si tratta del numero di una comunicazione; Descrizione: Effettuando l’operazione si ottiene un documento in formato xml della comunicazione corrispondente all’ID indicato. La descrizione dell’xml della comunicazione è disponibile su www.shab.ch oppure. www.simap.ch. Accessibilità: l’accesso all’operazione è consentito soltanto se l’utente è registrato. La comunicazione deve essere stata pubblicata. Se l’utente è un amministratore cantonale vengono visualizzate anche le comunicazioni «convalidate». 2.3.3.2 getNoticePdf(documentId) Argomenti: - documentId si tratta del numero di una comunicazione; Descrizione: Effettuando l’operazione si ottiene un documento in formato pdf della comunicazione corrispondente all’ID indicato. Accessibilità: l’accesso all’operazione è consentito soltanto se l’utente è registrato. Considerato che i documenti in pdf sono disponibili soltanto nel FUSC, anche l’operazione può essere effettuata soltanto nel FUSC. 2.3.4 getNoticeXmls(publishDate) Argomenti: - publishDate si tratta di una data di pubblicazione del FUSC; Descrizione: Effettuando l’operazione si ottiene un documento in formato xml di tutto il file. Il file intero contiene tutte le comunicazioni pubblicate alla data indicata. Come argomento occorre indicare una data di pubblicazione del FUSC. Accessibilità: l’accesso all’operazione è consentito soltanto se l’utente è registrato. L’operazione è accessibile soltanto nel FUSC. L’operazione può essere effettuata soltanto per i numeri pubblicati. KPS Documents Interfaccia SOAP del FUSC/Simap/FUC ZH Pagina 8/11
2.3.5 Operazione ad uso del foglio ufficiale del Cantone di Zurigo
Le operazioni seguenti vengono effettuate soltanto in relazione al foglio ufficiale del
Cantone di Zurigo: si tratta perciò di operazioni disponibili soltanto con la relativa
installazione.
• getActualCantonNoticeListForCategoryWithStatus
• getAttachment
• getProviderFromNotice
2.4 Messaggi di errore
La segnalazione di un errore può avvenire sia mediante codice di errore sia mediante
messaggio di errore. Si tratta di una segnalazione generica («fault»). Ad ogni «fault»
sono attribuiti due parametri: «code» e «message».
Il codice di errore viene trasmesso mediante l’operazione getFaultInfo.getCode().
Il messaggio che specifica il tipo di errore viene trasmesso con
getFaultInfo.getMessage().
Elenco dei messaggi di errore:
Codice di Descrizione del tipo di errore
errore
0 Internal error !
1 You do not have sufficient rights to perform this operation !
2 Date out of range !
10 Internal error in getAuthenticationObject!
20 Not authenticated!
21 Internal error in getNoticeList!
30 Error in service getNotice. Not authenticated!
31 Internal Error in getNoticeXml !
32 Error in service getNotice. Notice not available!!
35 Internal Error in getNoticeXmls !
36 Error in service getNoticeXmls. Not authenticated!
37 Error in service getNoticeXmls. Date not published!
40 Error in service getProvider. Not authenticated!
41 Internal error in getProviderFromNotice !
42 Internal error in getProvider !
50 Error in service getAttachment. Not authenticated!
51 Internal error in getAttachment !
52 No document in getAttachment !
KPS Documents Interfaccia SOAP del FUSC/Simap/FUC ZH Pagina 9/1160 Error in authentication. User is not a subscriber!
61 Error in getNoticeListForSubscription. Subscription id is not valid for the subscriber!
62 Error in getNoticeListForSubscription. Error processing search list!
70 Error in service getNoticePdf. Not authenticated !
71 Internal error in getNoticePdf !
72 No document in getNoticePdf !
2.5 Esempio di programma in Java
L’esempio di programma è finalizzato a illustrare l’esecuzione degli elementi
fondamentali della programmazione per un client in relazione a questo web service.
Nota: per il programma di cui sotto occorre prima di tutto generare classi di client. La
generazione di queste classi avviene mediante il comando
wsimport -keep -p [package Java per i dati generati]
-s [percorso per i file sorgente]
https://www.shab.ch/soapserver?wsdl
______________________________________________________________________________________________
import java.net.URL;
import java.text.SimpleDateFormat;
import java.util.Collections;
import java.util.GregorianCalendar;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import javax.xml.datatype.DatatypeFactory;
import javax.xml.datatype.XMLGregorianCalendar;
import javax.xml.namespace.QName;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.handler.MessageContext;
import de.autinform.exchange.common.soap.client.notice.Fault;
import de.autinform.exchange.common.soap.client.notice.LongArray;
import de.autinform.exchange.common.soap.client.notice.SoapServer;
import de.autinform.exchange.common.soap.client.notice.SoapServerService;
public class Example {
private final static SimpleDateFormat dateFormat = new SimpleDateFormat("dd.MM.yyyy",
Locale.getDefault());
public Example() {
}
public void main(String username, String password) {
// Erstellung einer Verbindung zum Soap Server
KPS Documents Interfaccia SOAP del FUSC/Simap/FUC ZH Pagina 10/11String servername = "www.shab.ch";
int port = 9191;
try {
URL url = new URL("http://" + servername + ":" + port +"/soapserver?wsdl");
QName serviceName = new
QName("http://notice.server.soap.common.exchange.autinform.de/",
"SoapServerService");
SoapServerService service = new SoapServerService(url,serviceName);
SoapServer servicePort = service.getSoapServerPort();
/******************* Authentication ******************************/
Map req_ctx =
((BindingProvider)servicePort).getRequestContext();
Map headers = new HashMap();
headers.put("username", Collections.singletonList(username));
headers.put("password", Collections.singletonList(password));
req_ctx.put(MessageContext.HTTP_REQUEST_HEADERS, headers);
/**********************************************************************/
boolean succesfulAuthentication = servicePort.getAuthentication();
if (succesfulAuthentication) {
System.out.println("Authentication successful!");
} else {
System.out.println("Authentication not successful!");
return;
}
GregorianCalendar c = new GregorianCalendar();
c.setTime(dateFormat.parse("26.01.2013"));
XMLGregorianCalendar publishDate =
DatatypeFactory.newInstance().newXMLGregorianCalendar(c);
LongArray arrayList = servicePort.getNoticeListForSubscriber(publishDate,
4711);
List noticeList = arrayList.getItem();
for (int i=0; iPuoi anche leggere
