Rest Service

<< Fare clic per visualizzazione il sommario >>

Percorso:  I servizi di Jamio openwork >

Rest Service

Descrizione

Le funzioni del connettore REST devono permettere di effettuare invocazioni a qualsiasi servizio REST, quindi devono prevedere diversi tipi di input, output e parametri di configurazione.

Per far questo, funzioni come Invoke() o InvokeS() (che restituisce Stream invece di string) devono avere molti parametri, però questo non vuol dire che l’utente li debba effettivamente usare: i parametri obbligatori sono ben pochi, e nella definizione del relativo ServiceTask nel Composer basta definire solo quelli effettivamente usati; inoltre nel file di configurazione Xml del connettore è possibile specificare valori di default per quasi tutti i parametri, per cui perfino parametri obbligatori potrebbero non essere definiti nel ServiceTask se sono specificati nella configurazione usata.

Questo permette anche di avere potenzialmente una serie di configurazioni diverse per lo stesso connettore, che definiscono, per esempio, “Chiamate REST a Twitter” (specificando il parametro di configurazione BaseUrl = “https://api.twitter.com/1.1/”), o “Gli ultimi 50 tweet di openwork” (specificando BaseUrl = “https://api.twitter.com/1.1/” e Resource = “statuses/user_timeline.json?screen_name=openwork&count=50”), e così via: questo può arrivare al caso limite di non definire alcun parametro di input nel ServiceTask che chiama la funzione Invoke() del connettore.

Inoltre esistono funzioni semplificate (SimpleGet() e SimplePost()) che hanno solo tre parametri, di cui due obbligatori (a meno di non aver specificato anche questi nel file di configurazione).

Molti servizi REST richiedono un’autenticazione; questa però può essere gestita in modi diversi (comunque supportati dal connettore): dalla semplice autenticazione con UserId e Password ad autenticazioni OAuth o di altro tipo, che solitamente prevedono il passaggio di una serie di valori di autenticazione in particolari Header ("Authorization" per OAuth), o come parametri della GET, o come dati della POST; comunque i valori da inserire in questi Header o parametri devono essere noti prima dell’invocazione del metodo del connettore (possono essere fissi ed inseriti nel file di configurazione o possono essere ricavati in qualche modo dal processo prima dell’invocazione del servizio REST).

Sono previsti anche servizi di upload o download di file, prevedendo invocazioni che hanno un parametro  di tipo Stream per “data” della POST o un returnValue di tipo Stream.

L’output di tipo string dell’invocazione ad un servizio REST può essere in diversi formati; mentre output in formati come l’HTML saranno utilizzati senza conversioni, per altri formati comuni (Json, Xml, CSV) possono essere usate funzioni di conversione fornite dal connettore (o varianti delle funzioni di invocazione) che restituiscono Dictionary<string, object> (DataSetValue) o List<object> (ArrayValue).

In alcuni casi i nomi dei campi nel Dictionary restituito dalle funzioni di invocazione possono avere caratteri non permessi nei custom type di Jamio (soprattutto nel caso di output in formato Xml, dove si ha, per esempio, “?xml”, o i nomi degli attributi preceduti da ‘@’): per gestire questi casi, e comunque quando si voglia effettuare una diversa mappatura fra i campi restituiti dall’invocazione REST e i campi del ‘Dato strutturato’ referenziato nel Composer per ricevere l’output, tutte le funzioni che restituiscono un Dictionary prevedono anche due parametri (facoltativi) che consentono la rimappatura dei nomi dei campi (non necessariamente tutti), indicando, per esempio, di convertire “?xml” in “xmlInfo” e “@pageid” in “pageid”.

Se si vogliono evitare eventuali valori null relativi ad alcuni campi nel Dictionary restituito da alcune funzioni, si può fornire anche un parametro (facoltativo) che permette di specificare, per ogni campo interessato (chiave nel Dictionary), il valore da assegnare a quel campo nel caso sia null.

Alcune invocazioni con i metodi POST o PUT prevedono di inviare dati in formato Json o Xml: per questo vengono fornite anche funzioni che permettono di convertire un Dictionary<string, object> (DataSetValue) in una stringa contenente gli stessi dati in formato Json o Xml; anche in questo caso è possibile chiedere la rimappatura dei nomi dei campi.

 

Proprietà

Proprietà di configurazione del servizio di tipologia DataSet.

Il parametro contiene i seguenti campi (tutti opzionali se non diversamente specificato):

 

Name

Description

Type

Optional

BaseUrl

The base url of the REST service (ex.: “https://api.twitter.com/1.1/”).

String

 

Resource

The resource (ex.: “statuses/show.json”).

String

 

Method

The request method to use to contact the REST resource (“GET”, “POST”, “DELETE”, …).

String

 

ContentType

The media type of the request (ex.: “application/x-www-form-urlencoded”, “text/plain”; see http://en.wikipedia.org/wiki/MIME_type)

String

 

Host

The Host header value to use in the HTTP request independent from the request URI; it consists of a hostname and an optional port number (ex.: “www.contoso.com:8080″).

String

 

UserAgent

the user-agent header value (ex.: “.NET Framework Test Client”)

String

 

Timeout

the number of milliseconds to wait before the request times out

Int32

 

MaximumAutomaticRedirections

the maximum number of redirection responses that the request follows; -1 indicates automatic redirections are not allowed

Int32

 

MaximumResponseHeadersLength

the maximum allowed length of the response headers, in kilobytes (1024 bytes); if MaximumResponseHeadersLength is not explicitly set, it defaults to 64 Kb; a value of -1  means no limit is imposed on the response headers received

Int32

 

CredentialsType

type of the authentication credentials associated with the request:

1 = None (credentials not required or otherwise specified, maybe through the “Authorization” header)

2 = NetworkCredentials (“UserName” and “Password” must be specified)

3 = DefaultNetworkCredentials (the network credentials of the current security context)

4 = DefaultCredentials (the system credentials of the application)

Int32

 

UserName

user name (required if “CredentialsType” = 2).

String

 

Password

password (required if “CredentialsType” = 2).

String

 

TrustAllCertificates

true if certificate errors must be ignored, false otherwise (defaults to false).

Boolean

 

ClientCerPath

path of the .cer client certificate, if needed for the REST invocation

String

 

 

Metodi

I metodi sono di seguito elencati:

Version

Restituisce la versione del connettore.

Invoke

Invoca un servizio REST.

InvokeH

Invoca un servizio REST.

JsonInvoke

Invoca un servizio REST.

JsonDataInvoke

Invoca un servizio REST.

JsonDataInvokeH

Invoca un servizio REST.

XmlInvoke

Invoca un servizio REST.

CsvInvoke

Invoca un servizio REST.

InvokeS

Invoca un servizio REST.

SendStream

Invoca un servizio REST tramite il metodo POST con dati di tipo Reference.

JsonSendStream

Invoca un servizio REST tramite il metodo POST con dati di tipo Reference.

XmlSendStream

Invoca un servizio REST tramite il metodo POST con dati di tipo Reference.

CsvSendStream

Invoca un servizio REST tramite il metodo POST con dati di tipo Reference.

SimpleGet

Invoca un servizio REST tramite il metodo GET.

JsonSimpleGet

Invoca un servizio REST tramite il metodo GET.

XmlSimpleGet

Invoca un servizio REST tramite il metodo GET.

CsvSimpleGet

Invoca un servizio REST tramite il metodo GET.

SimplePost

Invoca un servizio REST tramite il metodo POST.

JsonSimplePost

Invoca un servizio REST tramite il metodo POST.

XmlSimplePost

Invoca un servizio REST tramite il metodo POST.

CsvSimplePost

Invoca un servizio REST tramite il metodo POST.

ParametersToString

Converte una insieme di coppie Chiavi/Valori di parametri in un stringa equivalente.

Detokenize

Restituisce la stringa in ingresso dopo aver sostituito i token specificati con i valori corrispondenti.

SimpleDetokenize

Restituisce la stringa in ingresso dopo aver sostituito i token specificati con i valori corrispondenti.

JsonToDictionary

Converte una stringa in formato Json in un Dataset.

XmlToDictionary

Converte una stringa in formato Xml in un Dataset.

CsvToList

Converte una stringa in formato Csv in un ArrayValue.

DictionaryToJson

Converte un Dataset in una stringa che contiene l’equivalente Json.

DictionaryToXml

Converte un Dataset in una stringa che contiene l’equivalente Xml.

StreamToString

Converte un allegato da Stream in String.

StringToStream

Converte una stringa in un allegato di tipo reference in un processo.

GetStructure

Restituisce la struttura di Dataset.

GetValueList

Restituisce l'insieme di oggetti di valore dell'oggetto Dataset come elenco di una stringa.

GetFile

Ottiene un file dal file system.

UrlEncode

Codifica la stringa della Query .