API di piattaforma > Altri servizi

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