Pervasive Data Integrator. REST Invoker 2.0 Guide

Transcription

1 Pervasive Data Integratr REST Invker 2.0 Guide Pervasive Sftware Inc Riata Trace Parkway Building B Austin, Texas USA Telephne: (512) r (800) Fax: (512) inf@pervasive.cm Web:

2 See cpyrights.txt in the prduct installatin directry fr infrmatin n third-party and pen sftware cmpnents. REST Invker 2.0 Guide September 2012 ii

3 Cntents REST Invker Installatin Prerequisites... 1 Installing the Invker... 1 Installatin Prcess... 2 Verify Installatin in PDI... 2 DJ Message Optins Custm Headers Multipart Pst Optins Prperties and Errrs Sessin Prperties Step Prperties Errr Cnditins See Als iii

4 REST Invker 2.0 The purpse f this dcument is t help Pervasive custmers install and cnfigure the REST invker 2.0. In additin t the capabilities available in REST Invker 1.0, the REST Invker 2.0 nw supprts NTLM v2 authenticatin, multipart pst requests, and binary attachments with and withut base 64 encding. Unlike REST Invker 1.0, respnse headers are available as prperties f the target DJMessage, if ne is specified. Installatin Prerequisites 1. Verify that Pervasive Data Integratr 9.2.x r 10.2.x is installed: DI 9.2.x If any Pervasive tls are pen (i.e., Map Designer, Prcess Designer, etc.), click Help and then click Abut. G t the Prduct License tab, and lk fr Versin, apprximately half-way dwn the page. At the cmmand line, run djengine versin DI 10.2.x: If Pervasive Data Integratr 10.2.x is pen, click the dwn-facing arrw next t the help icn (red lifesaver and questin mark). Chse the Versin Infrmatin item. On the resulting screen, the ``Versin sectin shuld be the secnd line, beneath the ``Prduct Name line. The REST Invker 2.0 has been tested against 10.2.x and may nt wrk n different versins. 2. Verify that yu have clsed all Pervasive tls. This is imprtant fr installing new cnnectrs and invkers. 3. Verify that the REST Invker 2.0 is installed n yur machine: DI 9.2.x: G t C:\Dcuments and Settings\All Users\Applicatin Data\Pervasive\Csms9\Cmmn\Plug-Ins\ and lk fr a subflder called REST Invker. Within this flder, lk fr a flder called DI 10.2.x: G t C:\Pervasive\<di build number>\runtime\di9\plug-ins\ and lk fr a subflder called REST Invker. Within this flder, lk fr a flder called If these flders exist fr the versin f DI that yu are running, then the cmpnent has been installed. If this flder des nt exist, then the cmpnent is nt installed. Prceed t Installing the Invker. Nte If yu have nt received the necessary files, yur cntact frm Pervasive Services r Supprt can prvide them. Installing the Invker Nte Befre installing the invker, verify that it is nt already installed using the criteria described in Step 4 f Installatin Prerequisites. If yu must g thrugh the fllwing installatin steps, make sure yu first btain the necessary files frm yur Pervasive Supprt r Prfessinal Services cntact. 1

5 T install the Invker yu must d the fllwing: G thrugh the installatin prcess fr either v9 r v10. Verify that the invker has been installed using a PDI test prcess. This sectin tells hw t cmplete these tasks. Installatin Prcess 1. DI 9.2.x: 2. DI 10.2.x: Verify that all Pervasive prgrams are clsed Cpy the RESTInvker mcf.jar int: C:\Users\Applicatin Data\Pervasive\Csms9\Cmmn\Plug-Ins Verify that the server is ffline. T d s, g t Admin Actins. The first line will say Current Server Status. If this status is nt set t OFFLINE, click Change status t ffline and chse the number f minutes yu d like t wait fr the service t g ffline (fr example, if yu have an integratin running, yu might want t wait a few minutes fr the integratin t cmplete). G t Admin Prduct Extensins Click the dwn-facing blue and white arrw. If yu wuld like t add a descriptin t the cmpnent yu are adding, enter it in the white text bx. Then click the Brwse and Deply buttn. Navigate t the RESTInvker mcf.jar file n yur system. Then click Open. Yu shuld nw see an alert indicating that the cmpnent was deplyed successfully. The cmpnent shuld nw be visible in the Prduct Extensins chart. Turn the v10 server back nline by ging t Admin Actins and clicking Change status t nline and chse the number f minutes t wait fr thse changes t take effect. Verify Installatin in PDI 1. DI 9.2.x: a. Start the Pervasive Prcess Designer and pen a new prcess. b. Frm the list n the left, right-click Invkers and select Add. 2

6 c. When the Invkers windw appears, select REST Invker frm the Type list. This will autmatically add a list f parameters in the Invker windw. Yu may als chse a mre descriptive name fr this invker. Enter that name in the Invker Name field. (See the screensht belw.) Warning If REST Invker des nt appear in the Invker list, then the invker may nt have been installed prperly. Shut dwn all Pervasive tls, check t make sure that the.jar file was cpied t the crrect lcatin (see Step 4 f Installatin Prerequisites, abve), and restart the Pervasive tls. 3

7 d. As shwn in the image abve, enter the necessary parameters t cnnect t the web service yu ll be wrking with. At a minimum, the fllwing parameters will be needed. Check with the administratr f the endpint if ther parameters are needed. Fr example, systems that use NTLM v2 authenticatin may require a username, passwrd, and dmain name. Prtcl Chse the crrect prtcl fr the web service yu are accessing. Fr example, if yu are using an HTTPS URL, and an apprpriate trust stre has nt been set up fr the web service yu are accessing, chse HTTPSDebug. URL The URL f the web service yu are trying t ping. May be in the frm f an IP address r server name. If a particular prt is required, include that here. Fr example: NOTE: The URL shuld be encded prperly befre being entered in the invker step. Cntact the administratr f yur web service endpint if yu are nt sure what kind f encding is required. Cntent-type The cntent-type f the request message. 4

8 e. Click the Invkers icn in the far-left tlbar. Then click the prcess canvas t add a new invker step. 5

9 f. Duble-click the new invker step t pen the Prperties windw. Of nte, frm here yu can d the fllwing: i. Specify surce and target DJMessages ii. Set the HTTP methd f the request yu want t make (e.g., GET, POST, TRACE) iii. Specify a SOAP Actin iv. Specify a query string. This string will be URL encded in the applicatin/x-wwwfrm-urlencded MIME frmat. v. Change the default retry cunt and timeut limit 6

10 2. DI 10.2.x a. Open the v10 prcess designer: b. Drag an Invker step nt the design palette. c. With the new invker step selected, in the sliding drawer at the bttm f the screen click the Create a new ne link next t Chse an invker 7

11 d. When the Invkers windw appears, select REST Invker frm the Type list. This will autmatically add a list f parameters in the Invker windw. Yu may als chse a mre descriptive name fr this invker. Enter that name in the Invker Name field. (See the screensht belw.) Warning If REST Invker des nt appear in the Invker list, then the invker may nt have been installed prperly. Shut dwn all Pervasive tls, check t make sure that the.jar file was cpied t the crrect lcatin (see Step 4 f Installatin Prerequisites, abve), and restart the Pervasive tls. 8

12 e. As shwn in the image abve, enter the necessary parameters t cnnect t the web service yu ll be wrking with. At a minimum, the fllwing parameters will be needed. Check with the administratr f the endpint if ther parameters are needed. Fr example, systems that use NTLM v2 authenticatin may require a username, passwrd, and dmain name. Prtcl Chse the crrect prtcl fr the web service yu are accessing. Fr example, if yu are using an HTTPS URL, and an apprpriate trust stre has nt been set up fr the web service yu are accessing, chse HTTPSDebug. URL The URL f the web service yu are trying t ping. May be in the frm f an IP address r server name. If a particular prt is required, include that here. Fr example: NOTE: The URL shuld be encded prperly befre being entered in the invker step. Cntact the administratr f yur web service endpint if yu are nt sure what kind f encding is required. Cntent-type The cntent-type f the request message. f. When yu are dne, click Dne. g. With the invker step still selected, in the sliding panel at the bttm f the screen under the heading Actin, chse Execute. h. Nw, yu shuld see sme Parameters and Prperties ptins t the right f the same panel. Under Parameters chse yur input and utput DJ Messages. 9

13 i. Under Prperties, yu can specify fields that are required fr the specific call yu are making. The image belw shws an example f the ptins yu ll be presented with. Ntably, yu can: i. Set the HTTP methd f the request yu want t make (e.g., GET, POST, TRACE) ii. Specify a SOAP Actin iii. Specify a query string. This string will be URL encded in the applicatin/x-wwwfrm-urlencded MIME frmat. iv. Change the default retry cunt and timeut limit v. Specify a surce flder fr a multipart pst request 10

14 DJ Message Optins Users can custmize REST Invker requests by adding prperties t the surce DJ Message. The fllwing sectins describe the specific ptins available fr these custmisatins, alng with examples. Custm Headers Any REST Invker call can cntain custm headers that are specific t the web service being accessed. T add a custm header, add the fllwing prperty t the surce DJ Message: srcmsg.prperties( H.<HeaderName> ) = <Header Value> Fr example, a specific call might require a header called Authrizatin that takes a tken fr its value. This call might lk like: msg1.prperties( Authrizatin ) = 09bf14tzrw426b71fx6adfad12 Multipart Pst Optins When making multipart pst requests, there are a few ptins that the user has t custmize their request. These include specifying the files in a flder shuld be sent, the cntent type fr a specific file, and specifying the name field f the cntent-dispsitin header. Specify a File t Send When a user specifies a request flder, this signifies t the T specify the files, the syntax is: srcmsg.prperties( F.<FileName> ) = <FilePath> where the <FilePath> is relative t the flder that is specified and the name f the file, including the extensin. Specify the Cntent-Type f a File By default, each file in the multipart pst request will take the glbal cntent-type (the cntent-type yu set in the invker settings). Hwever, it is pssible that sme f the files yu send will have a different cntent-type. In rder t specify the cntent-type fr a specific file, use the syntax: srcmsg.prperties( C.<FileName> ) = <cntent-type> The file name shuld include the file s extensin. Specify the Name Field f the Cntent-Dispsitin Header fr a File Certain web services may require the name field f the cntent-dispsitin header t have a certain value in rder t successfully uplad a file. Fr example, a web service may expect a cntent-dispsitin header f the frm: Cntent-Dispsitin: attachment; filename= accunts.csv ; name= spreadsheet If a file in a multipart pst needs a specific name, the user can specify the crrect name with the syntax: srcmsg.prperties( N.<FileName> ) = <cntent disp. name> By default, the name field is set t file fr each file in the multipart pst. 11

15 Prperties and Errrs The fllwing tables prvide details abut the REST Invker 2 sessin prperties, step prperties, and errrs. Sessin Prperties Prperty Descriptin Default Value Prtcl URL Send Surce Via Message Encding Use Base64 Encding Cntent Type HTTP Username HTTP Passwrd Dmain (NTLM nly) Prxy Server Prxy Prt Whether t send the request via HTTP r HTTPS prtcl. The HTTPS prtcl requires a trust stre t be set up n the calling machine in rder fr the request t be successfully authenticated. The HTTPS Debug setting accepts all certificates. Nte that accepting all certificates is nt recmmended, as this can be insecure. Hwever, if yu must use the HTTPS prtcl and yu d nt have a trust stre set up fr the hst yu are cnnecting t, yu must use HTTPS Debug r yur request will fail. Specify the lcatin f the server. Can be a URL r an IP address. If a particular prt is required, include that here. Fr example: Whether r nt t send the message thrugh the URL r the bdy f a DJ Message. Chse the character encding set that will be used fr bth the request and the respnse. The tw supprted encdings are UTF-8 and ISO If a binary attachment is t be sent, shuld the attachment be encded in base 64 befre being sent. Indicates the Internet media type f the message cntent. Of the frm type/subtype If username/passwrd r NTLM type authenticatin is required with each call, then specify the username. If username/passwrd r NTLM type authenticatin is required with each call, then specify the passwrd. If NTLM authenticatin is required, then specify the dmain t which t cnnect. If using a prxy, specify the prxy server. Can be a URL r an IP address. The prt t use fr the prxy server. HTTP BODY UTF-8 N text/xml 12

16 Prperty Descriptin Default Value Prxy Username Prxy Passwrd If username/passwrd type authenticatin is required fr the prxy server, then specify the username. If username/passwrd type authenticatin is required fr the prxy server, then specify the passwrd. Step Prperties Prperty Descriptin Default Value HTTP Methd URL Query String SOAP Actin Cnnect Retry Cunt Cnnect Timeut Lg HTTP Headers Read Surce File Read Surce Flder Write Respnse File Indicate the type f actin t take fr this call, e.g., GET, POST, TRACE. Specify a query string, if applicable. This string will be URL encded by the invker accrding t the applicatin/x-www-frm-urlencded specificatin. Specify the SOAP actin header, if applicable. Specify the number f times t retry the call in the event f a failure. Specify the number f secnds t wait befre cnsidering the call as timed ut. Whether t write the request and respnse headers t the lg Fr uplading files, e.g., uplading binary attachments, specify the file that is t be uplad. Fr multipart psts, specify the flder lcatin that cntains the file that shuld be upladed. If this field is ppulated, the invker will assume that this is a multipart pst request. By default, all f the files in the specified flder will be added in the request. Hwever, users can specify particular files using the fllwing syntax in a scripting step befre the invker is called: requestmsg.prperties( F.<filename> ) = <filepath> This line must be present fr each file that is specified. See Multipart Pst Optins abve fr mre infrmatin. If the respnse bdy shuld be written t a file, specify that here. NOTE: If a respnse file is specified, then the respnse bdy will nt be written t the bdy f the target DJ Message. POST 5 30 True 13

17 Prperty Descriptin Default Value Write Respnse Flder If multiple respnses r files are expected, a flder can be specified t hld thse files. Errr Cnditins Cde Name Descriptin Pssible Reasn 0 OK N errr. Used fr all inf messages. 50 UNSPECIFIED An unexpected errr ccurred. Displayed fr all runtime errrs. 4 READ ERROR A file, input stream, r web service respnse culd nt be read. 27 CLOSE ERROR A file r input stream culd nt be clsed. 20 BAD FILE TYPE The specified directry r file des nt exist. 11 RECORD TOO BIG A file r input stream is t large t be read by the invker (the maximum size is characters). 34 INVALID An ptin is invalid. The invker was redirected t an invalid lcatin (e.g., n lcatin header was specified) 44 NOT SUPPORTED An ptin is nt specified. The invker culd nt encde a binary attachment t base 64 due t a charset errr. See Als Errr Cdes and Messages Reference Manual fr additinal errr cdes. 14