Metodo 1 Web Services Farmadati

Ultimo
aggiornamento: 22/09/2021 MOE‐A018 Rev. 08

WEB SERVICES METHOD 1
INTERROGAZIONE REMOTA

©Farmadati Italia s.r.l. Tutti i diritti riservati.
E‐mail: bdf@farmadati.it ‐ Web: www.farmadati.it
Via San Francesco, 8 ‐ 29121 Piacenza ‐ Tel +39 0523 336933 ‐ Fax +39 0523 335391
C.C.I.A.A. PC n. 132067 ‐ Reg. Soc. Trib. PC n. 14832 ‐ Cod. Fisc. e P.IVA 01169830336
Indice

1. Introduzione pag. 3

2. Requisiti per l’utilizzo pag. 3

3. Endpoint Address pag. 3

4. WSDL pag. 3

5. Servizio News pag. 3

6. Servizi pag. 4

6.1. GetEnabledDataSet pag. 4

6.2. GetSchemaDataSet pag. 6

6.3. ExecuteQuery pag. 7

7. Esempi di chiamate ai Servizi pag. 13

8. Configurazione Binding lato client pag. 14
Pag. 2 di 14
Via S. Francesco, 8 ‐ 29121 Piacenza ‐ Tel +39 0523 336933 ‐ Fax +39 0523 335391

1) Introduzione
Il presente documento descrive i Web Services implementati da Farmadati Italia per l’interrogazione
remota delle proprie Banche Dati.

2) Requisiti per l’utilizzo
 Connessione Internet DSL
 Framework/linguaggio di programmazione che consenta la comunicazione ai Web Services
tramite protocollo SOAP

3) Endpoint Address
L’URL endpoint che l’applicazione Client deve specificare per accedere ai Web Services Farmadati
Italia è (a seconda del protocollo che si desidera utilizzare):
HTTP: http://webservices.farmadati.it/WS2/FarmadatiItaliaWebServicesM1.svc
HTTPS: https://webservices.farmadati.it/WS2S/FarmadatiItaliaWebServicesM1.svc

4) WSDL
La descrizione dei Web Services Farmadati Italia è disponibile al seguente indirizzo (a seconda del
protocollo che si desidera utilizzare):
HTTP: http://webservices.farmadati.it/WS2/FarmadatiItaliaWebServicesM1.svc?singleWsdl
HTTPS: https://webservices.farmadati.it/WS2S/FarmadatiItaliaWebServicesM1.svc?singleWsdl

5) Servizio News
Per ogni Tabella è presente un servizio di News Feed, fornito tramite documento XML, nel quale
vengono trasmesse le comunicazioni relative a variazione di contenuti o del tracciato dei campi
(Per dettagli vedere paragrafo 6.1).
Pag. 3 di 14
6) Servizi

I Web Services disponibili sono:
 GetEnabledDataSet
 GetSchemaDataSet
 ExecuteQuery

6.1) GetEnabledDataSet
Il Servizio fornisce all’Utente l’elenco delle Tabelle abilitate.

Parametri in INPUT:
<GetEnabledDataSet>
<Username>string</Username>
<Password>string</Password>
</GetEnabledDataSet>

Parametri in OUTPUT:
<GetEnabledDataSet_Output>
<CodEsito>string</CodEsito>
<DescEsito>string</DescEsito>
<SetDati>
<Key>string</Key>
<Description>string</Description>
<UrlNews>string<UrlNews>
<SchemaCode>int</SchemaCode>
</SetDati>
<SetDati>
<Key>string</Key>
<UrlNews>string<UrlNews>
</SetDati>
</GetEnabledDataSet_Output>

Pag. 4 di 14
Chiamando il Servizio con i parametri in input:
 Username
 Password

si otterrà in risposta un oggetto GetEnabledDataSet_Output, formato da:
 [CodEsito] ‐ Codice Esito: “OK” se l’esito della chiamata al Servizio è positivo, “ERR” se negativo
 [DescEsito] ‐ Descrizione Esito: “OK” se esito positivo, messaggio dell’errore se in caso negativo
 Array di oggetti [Tabelle]

Ogni oggetto Tabella è composto da:
 [Key] ‐ Codice della Tabella (Es: “PARAFARM”)
 [Description] ‐ Descrizione della Tabella ‐ (Es: “Tabella per prodotti Parafarmaceutici”)
 [UrlNews] ‐ WebURL del file XML di News
Questo file, di struttura simile ad un Feed RSS in formato XML, contiene tutte le
comunicazioni trasmesse da Farmadati Italia riguardanti la Tabella.
Ad esempio: comunicazioni relative a variazioni di tracciato, informazioni sul contenuto e
significato dei campi, avvisi sulle eventuali manutenzioni del Servizio.
 [SchemaCode] ‐ Codice Schema Tabella (versione del tracciato record)
Pag. 5 di 14
6.2) GetSchemaDataSet
Il Servizio fornisce all’Utente lo Schema (tracciato record) della Tabella specificato in Input.

Parametri in INPUT:
<GetSchemaDataSet>
<Password> string</Password>
<CodiceSetDati>string</CodiceSetDati>
</GetSchemaDataSet>

<GetSchemaDataSet_Output>
<CodEsito> string</CodEsito>
<DescEsito> string</DescEsito>
<Field>
<IdNum>int</IdNum>
<Key>string</Key>
<Type>string</Type>
<Length>string</Length>
</Field>
<Field>
<IdNum>int</IdNum>
<Key>string</Key>
<Type>string</Type>
<Length>string</Length>
</Field>
</GetSchemaDataSet_Output >

Chiamando il Servizio con i parametri in input:
 Username
 Password
 [CodiceSetDati] ‐ Codice della Tabella (parametro [Key], paragrafo 6.1)

si otterrà in risposta un oggetto GetSchemaDataSet_Output, formato da:
 [CodEsito] ‐ Codice Esito: “OK” se l’esito è positivo, “ERR” se negativo
 [DescEsito] ‐ Descrizione Esito: “OK” se esito positivo, messaggio dell’errore se negativo
 Array di oggetti [Field]

Ogni oggetto Field è composto da:
 [IdNum] ‐ Posizione del campo nello Schema della Tabella (intero progressivo)
Il Campo con [IdNum] valorizzato a 1 è la Chiave univoca della Tabella
 [Key] ‐ Codice identificativo del campo (Es: “FDI_0041”)
 [Description] ‐ Descrizione logica del campo (Es: “Ragione sociale ditta produttrice 1”)
 [Type] ‐ Formato del contenuto del campo (Es: “VARCHAR”)
 [Length] ‐ Lunghezza massima del campo (Es: ”40”)
Esempio:
Pag. 6 di 14
Key Type Description Length
FDI_0001 VARCHAR Codice prodotto 9
FDI_0004 VARCHAR Descrizione prodotto 20
FDI_0245 VARCHAR Commercio 1
FDI_0467 NUMERIC Prezzo 1 8,3
FDI_0249 DATE Data 1a registrazione

 [SchemaCode] ‐ Codice Schema Tabella (versione del tracciato record)

6.3) ExecuteQuery
Il Servizio permette all’Utente di effettuare Query personalizzate sulla Tabella specificato in Input.

Parametri in INPUT:
<ExecuteQuery>
<Password>string</Password>
<CodiceSetDati>string</CodiceSetDati>
<CampiDaEstrarre>
<string>string</string>
<string>string</string>
</CampiDaEstrarre>
<Filtri>
<Filter>
<Key>string</Key>
<Operator>string</Operator>
<OrGroup>int</OrGroup>
<Value>string</Value>
</Filter>
<Filter>
<Key>string</Key>
<Operator>string</Operator>
<OrGroup>int</OrGroup>
<Value>string</Value>
</Filter>
</Filtri>
<Ordinamento>
<Order>
<Key>string</Key>
<OrderType>string</OrderType>
</Order>
<Order>
<Key>string</Key>
<OrderType>string</OrderType>
</Order>
</Ordinamento>
<Distinct>boolean</Distinct>
<Count>boolean</Count>
<PageN>int</PageN>
<PagingN>int</PagingN>
</ExecuteQuery>

Pag. 7 di 14
<ExecuteQuery_Output>
<CodEsito>string</CodEsito>
<DescEsito>string</DescEsito>
<RecordsPerPage >int</RecordsPerPage>
<NumRecords >int</NumRecords>
<Page>int</Page>
<OutputValue>string</OutputValue>
</ExecuteQuery_Output>

Di seguito il significato dei parametri in input necessari per effettuare la chiamata al Servizio
ExecuteQuery:

 [Username]
 [Password]

 [CodiceSetDati]: Codice della Tabella su cui si desidera effettuare la Query

 [CampiDaEstrarre]: Array di Codici identificativi dei campi che si desidera estrarre in output (la
lista completa dei campi che compongono la Tabella è ottenuta tramite il Servizio
GetSchemaDataSet – vedi paragrafo 6.2).
Se si ha la necessità di estrarre dalla Query tutti i campi presenti nella Tabella, è possibile
indicare nella prima stringa dell’Array il valore speciale “ALL” (vedi esempi paragrafo 7).

 [Filtri]: Array di oggetti [Filter]. Un filtro è una condizione applicata alla Query.
Ogni oggetto Filter è composto dai seguenti parametri:
 [Key]: Codice identificativo del Campo

 [Operator]: E’ una stringa alfanumerica che rappresenta l’operatore di confronto.
Gli Operatori disponibili sono:

Per tutti i formati:
o “=” (uguale a)
o “<>” (diverso da)
o “CAMPO VUOTO”
o “CAMPO NON VUOTO”

Per valori alfanumerici:
o “CONTIENE”
o “NON CONTIENE”
o “INIZIA PER”
o “TERMINA PER”

Per valori numerici:
o “>” (maggiore di)
o “<” (minore di)
o “>=” (maggiore o uguale a)
Pag. 8 di 14
o “<=” (minore o uguale a)

 OrGroup:
Gli oggetti Filter con OrGroup valorizzato a 0 (zero) sono eseguiti in AND.
Per impostare due o più oggetti Filter in OR tra loro, valorizzare il parametro OrGroup con
un numero intero maggiore di zero.
Ciascun gruppo di oggetti Filter in OR (con stesso OrGroup) è eseguito in AND.

Esempio 1:
Key (CAMPO) Operator (OPERATORE) Value (VALORE) OrGroup(GRUPPO FILTRI IN OR)
FDI_0248 = 10 0
FDI_1228 <> MEDICAL 0
FDI_1023 CONTIENE PARACETAMOLO 1
FDI_1023 CONTIENE IBUPROFENE 1

Il Servizio elabora i filtri impostati nell’esempio 1 nel seguente modo:
ESTRAI TUTTI I RECORD CHE SODDISFANO LA CONDIZIONE FDI_0248 = 10 AND FDI_1228 <> ‘MEDICAL’ AND
(FDI_1023 CONTIENE PARACETAMOLO OR FDI_1023 CONTIENE IBUPROFENE)

Esempio 2:
Key (CAMPO) Operator (OPERATORE) Value (VALORE) OrGroup(GRUPPO FILTRI IN OR)
FDI_0248 = 10 1
FDI_1228 <> MEDICAL 1
FDI_1023 CONTIENE PARACETAMOLO 2
FDI_1023 CONTIENE IBUPROFENE 2

Il Servizio elabora i filtri impostati nell’esempio 2 nel seguente modo:
ESTRAI TUTTI I RECORD CHE SODDISFANO LA CONDIZIONE (FDI_0248 = 10 OR FDI_1228 <> ‘MEDICAL’) AND
(FDI_1023 CONTIENE PARACETAMOLO OR FDI_1023 CONTIENE IBUPROFENE)

 [Value]: Valore del Campo che deve soddisfare la condizione impostata

 [Ordinamento]: Array di oggetti [Order].
E’ possibile specificare uno o più criteri di ordinamento dei record di Output prodotti
dall’elaborazione della Query.
Ogni oggetto Order è composto da:
 [Key]: Codice identificativo del Campo
 [OrderType]: Tipo di ordinamento applicato, è possibile valorizzare questo parametro con
le stringhe “CRESCENTE” oppure “DESCRESCENTE”, se non valorizzato di default sarà
applicato un ordinamento CRESCENTE.
L’ordinamento è applicato in sequenza dal primo all’ultimo campo dell’Array.

Esempio:
Key(CAMPO) TIPO ORDINAMENTO (OrderType)
FDI_0248 CRESCENTE
FDI_1228 DECRESCENTE

Il Servizio elabora i l’ordinamento impostato nell’esempio nel seguente modo:
ORDINA LA QUERY PER IL CAMPO FDI_0248 IN MODO CRESCENTE, POI PER FDI_1228 IN MODO DECRESCENTE.

Pag. 9 di 14
 [Distinct] (booleano*): Se valorizzato a true, la Query restituisce univocamente tutti i valori che
può assumere il campo specificato nell’Array CampiDaEstrarre.

 [Count] (booleano*): Se valorizzato a true, la Query restituisce il numero dei record referenziati
nella Tabella specificato (considerando eventuali filtri impostati).

 [PageN]: Numero di pagina richiesto. La prima pagina è 1.

 [PagingN]: Numero di record per pagina. Valore minimo 1, massimo 100.

*I parametri booleani nella richiesta XML sono CASE SENSITIVE e vanno indicati in minuscolo.
Valori ammessi: “true”, “false”, 1, 0.

Nota importante: L’output dei record è paginato, ogni pagina contiene a scelta da 1 a 100 record.
Per scaricare tutti i record prodotti dalla Query effettuata, è necessario chiamare il Servizio una o più
volte di seguito, indicando in input il numero di pagina in modo incrementale fino ad ottenere in
risposta una pagina vuota, identificabile con i parametri OutputValue = “EMPTY” e/o NumRecords =
0.

Il Servizio ExecuteQuery restituisce OUTPUT differenti a seconda dei parametri specificati in INPUT.
Di seguito il dettaglio delle tipologie di chiamata al Servizio:

1. Chiamata STANDARD (in OUTPUT sono restituiti i record composti dai Campi Da Estrarre indicati e
che soddisfano le condizioni di filtro ed ordinamento eventualmente impostate)

Parametri INPUT:
 Username
 Password
 CodiceSetDati
 CampiDaEstrarre: indicare uno o più codici campo, oppure “ALL”
 Filtri: non valorizzato, oppure uno o più oggetti Filter
 Ordinamento: non valorizzato, oppure uno o più oggetti Order
 Distinct: indicare a false
 Count: indicare a false
 PageN: indicare la pagina richiesta (a partire dalla pagina 1)
 PagingN: indicare il numero dei record che conterranno le pagine (da 1 a 100)

Pag. 10 di 14
Parametri OUTPUT:
 CodEsito: “OK” se esito positivo, “ERR” se esito negativo
 DescEsito: “OK” se esito positivo, messaggio di errore se esito negativo
 RecordsPerPage: numero di record per pagina (parametro a scelta impostati in input
 NumRecords: record effettivi restituiti in output contenuti dalla pagina richiesta
 Page: numero di pagina richiesta
 OutputValue: stringa XML contenente i record della pagina richiesta
NB: i tag XML dei campi vuoti (con valore NULL) non sono presenti all’interno del record.

2. Chiamata VALORI UNIVOCI (in OUTPUT sono restituiti i valori univoci che assume il campo
specificato in INPUT nei Campi Da Estrarre)

Parametri INPUT:
 Username
 Password
 CodiceSetDati
 CampiDaEstrarre: indicare il solo codice del campo scelto
 Filtri: non specificare
 Ordinamento: solo sul campo scelto, in modo CRESCENTE o DESCRESCENTE
 Distinct: indicare a true
 Count: indicare a false
 PageN: indicare la pagina richiesta (a partire dalla pagina 1)
 PagingN: indicare il numero dei record che conterranno le pagine (da 1 a 100)

Parametri OUTPUT:
 RecordsPerPage: numero di record per pagina impostati in input
 NumRecords: record effettivi restituiti in output contenuti dalla pagina
 Page: numero di pagina impostata in input
 OutputValue: stringa XML contenente i valori univoci della pagina richiesta
NB: i tag XML dei campi vuoti (con valore NULL) non sono presenti all’interno del record.

Pag. 11 di 14
3. Chiamata CONTEGGIO RECORD (in OUTPUT è restituito il numero dei record referenziati nella
Tabella specificato considerando eventuali filtri impostati)

Parametri INPUT:
 Username
 Password
 CodiceSetDati
 CampiDaEstrarre: indicare “ALL”
 Filtri: non valorizzato, oppure uno o più oggetti Filter
 Ordinamento: non valorizzato
 Distinct: indicare a false
 Count: indicare a true
 PageN: non significativo, indicare 1
 PagingN: non significativo, indicare 1

Parametri OUTPUT:
 RecordsPerPage: non significativo
 NumRecords: numero dei record che soddisfano i criteri impostati (numero intero)
 Page: non significativo
 OutputValue: numero dei record che soddisfano i criteri impostati (in formato alfanumerico)

Pag. 12 di 14
7) Esempi di chiamate ai Servizi
Di seguito sono riportati esempi sulle chiamate ai Servizi in linguaggio C#.
In ambiente MS Visual Studio (Framework .Net) per poter utilizzare i Web Services Farmadati Italia è
necessario aggiungere ai Riferimenti ai Servizi (Service References) della propria applicazione l’indirizzo
di Endpoint specificato al paragrafo 4.

All’interno della propria classe dichiarare ed inizializzare il Client di comunicazione:
//INIZIALIZZO IL CLIENT
FarmadatiItaliaWebServicesM1Client FDClient = new FarmadatiItaliaWebServicesM1Client();

//CHIAMATA AL SERVIZIO GetEnabledDataSet:
GetEnabledDataSet_Output DSEnabled = FDClient.GetEnabledDataSet(Username, Password);
if (DSEnabled.CodEsito != "OK") { MessageBox.Show("ERRORE: " + DSEnabled.DescEsito); return; }

//CHIAMATA AL SERVIZIO GetSchemaDataSet:
GetSchemaDataSet_Output SchemaDS = FDClient.GetSchemaDataSet(Username, Password, "FARM");
if (SchemaDS.CodEsito != "OK") { MessageBox.Show("ERRORE: " + SchemaDS.DescEsito); return; }

//ESEMPI DI CHIAMATE AL SERVIZIO ExecuteQuery:
//1) INTERROGO la Tabella CON UN FILTRO (OTTENGO TUTTI I VALORI DEI CAMPI RELATIVI ALL’AIC “00024591”)
Filter [] filtri = new Filter[1];
filtri[1].Key="FDI_0001";
filtri[1].Operator="=";
filtri[1].Value="00024591";
filtri[1].OrGroup=0;

ExecuteQuery_Output RS = FDClient.ExecuteQuery(Username, Password, "FARM", new string[] {"ALL"}, filtri, r, false,
false, 1, 1);
if (RS.CodEsito != "OK") { MessageBox.Show("ERRORE: " + RS.DescEsito); return; }
if (RS.OutputValue == "EMPTY") { MessageBox.Show("Nessun record soddisfa i criteri impostati"); return; }

//2) INTERROGO la Tabella CON UN FILTRO (OTTENGO I RECORDS CHE SODDISFANO IL FILTRO IMPOSTATO)
Filter [] filtri = new Filter[1];
filtri[1].Key="FDI_0234";
filtri[1].Operator="=";
filtri[1].Value="IBUPROFENE";
filtri[1].OrGroup=0;

ExecuteQuery_Output RS = FDClient.ExecuteQuery(Username, Password, "FARM", new string[] {"ALL"}, filtri, r, false,
false, 1, 100);
if (RS.CodEsito != "OK") { MessageBox.Show("ERRORE: " + RS.DescEsito); return; }
if (RS.OutputValue == "EMPTY") { MessageBox.Show("Nessun record soddisfa i criteri impostati"); return; }

//(SUGGERIMENTO: UTILIZZO L’OGGETTO DataSet DEL FRAMEWORK .NET PER GESTIRE I RECORD OTTENUTI IN OUTPUT)
DataSet dataSet = new DataSet();
dataSet.ReadXml(new System.Xml.XmlTextReader(new System.IO.StringReader(RS.OutputValue)));

Pag. 13 di 14
8) Configurazione Binding lato Client

NOTA IMPORTANTE:
Per un completo funzionamento della comunicazione tra l’applicazione Client ed i Servizi Web Farmadati
e per scaricare correttamente i pacchetti byte delle Tabelle, potrebbe essere necessario estendere il
limite massimo dei timing e delle dimensioni dei messaggi in ingresso nella configurazione del binding.

Ad esempio, su framework .NET modificare il file di configurazione dell’applicazione Client (app.config),
settando i parametri
maxBufferSize, maxBufferPoolSize, maxReceivedMessageSize, maxStringContentLength,
maxArrayLength, maxBytesPerRead, maxNameTableCharCount
ad un valore maggiore, ad esempio: 2147483647

Es:
<basicHttpBinding>

<binding name="BasicHttpBinding_FarmadatiItaliaWebServicesM2"
maxBufferSize="2147483647" maxReceivedMessageSize="2147483647"
closeTimeout="00:15:00" openTimeout="00:15:00" receiveTimeout="00:15:00"
sendTimeout="00:15:00">

<readerQuotas
maxDepth="2147483647"
maxStringContentLength="2147483647"
maxArrayLength="2147483647"
maxBytesPerRead="2147483647"
maxNameTableCharCount="2147483647"/>

</binding>

</basicHttpBinding>

Pag. 14 di 14

Metodo 1 Web Services Farmadati

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Metodo 1 Web Services Farmadati

Caricato da

Copyright:

Formati disponibili

Ultimo

Potrebbero piacerti anche