SNIPPETアクションからAPI呼び出しを行う

SNIPPETアクションからREST呼び出しやSOAP API呼び出しを行うことができます。これは、StudioスクリプトでWebサービスに接続するための、サポートされている方法の1つです。SOAP Webサービスに接続している場合、またはAPI呼び出しにXMLが含まれている場合は、このメソッドを使用する必要があります。しかし、RESTful API呼び出しやJSONを含む呼び出しを行うには、REST APIアクションを使用するのが好ましい方法です。

応答にHTTPステータスコードが表示されるだけでなく、-1コードが表示されることもあります。これは応答でエラーが発生したことを示す内部コードです。

SNIPPETアクションでRESTful Webサービスに接続する

Studioスクリプトを使用して、SnippetアクションでRESTプロキシを使用してRESTful APIに接続できます。GetRestProxy()関数を使用してこのサービスにアクセスできます。RESTプロキシを使用すると、スクリプトでリモートのウェブサーバーとやり取りできるようになります。そのために使用できるプロパティや関数が用意されています。プロパティと機能については後述します。CXoneプラットフォームにより、REST APIは最大32 KBのデータを返すことができます。この制限は、レベルで課され、プラットフォーム厳格に強制されます。

RESTプロキシでは、動的データオブジェクトを使用する必要があります。動的データタイプにより、スクリプトはXMLやJSONでフォーマットされたレスポンスを扱うことができます。ダイナミックデータオブジェクトは、これらの形式のデータを受け取り、読み取ることができます。XMLまたはJSONに変換できるオブジェクトを動的に作成することもできます。これらの機能は、RESTful APIを使用するために必要です。

RESTプロキシを使用するには、スクリプトにSnippetアクションを追加し、[Snippet editor ]ウィンドウを開きます。以下の構文でGetRESTProxy()関数を呼び出します:

ASSIGN proxy = GetRESTProxy() 
 proxy.<property | function>([parameters]) 

<property | function>については、以下のセクションで説明するプロパティと関数から選択します。

プロパティ

プロパティ 詳細
StatusCode

MakeRestRequest()の呼び出しに続くHTTPステータスコードを収容します。このプロパティは変更できません。その関数が失敗した場合、ステータスコードは保持されなくなります。

StatusDescription MakeRestRequest()の呼び出しに続くHTTPステータスの説明を収容します。このプロパティは変更できません。
ContentType

デフォルトのcontent-typeヘッダーのオーバーライドを許可します。デフォルトはapplication/x-www-form-urlencodedです。

呼び出しによっては、ヘッダーを変更する必要があるかもしれません。たとえば、JSONを送信する場合、これをapplication/jsonに変更します。このプロパティを変更する必要があります。

ProxyTimeoutSeconds 申請タイムアウトを変更できます。デフォルトは10秒です。このプロパティを変更する必要があります。

関数

以下の表は、RESTful APIに接続する際に使用できる関数についての情報です。文字列のエンコードやハッシュを行うRESTプロキシ関数もあります。

関数 詳細
MakeRestRequest(p1, p2, p3, p4)

指定されたURLに対してHTTPリクエストを実行します。ここで、

  • P1:リクエストのURL、文字列
  • P2:API呼び出しのペイロード、文字列
  • P3:受諾ヘッダーと応答パーサーセレクター、数値または文字列:
    • 0:application/json
    • 1:text/xml
    • 2:application/json (応答ボディは無視)
    • 3:text/xml (応答ボディは無視)
      • "JSON" - application/json
      • "XML - text/xml
  • P4:REST APIの動詞、文字列
AddHeader HTTP申請にカスタムヘッダーを追加します。
ClearHeaders AddHeaderで追加されたカスタムヘッダーをすべてクリアします。

ASSIGN proxy = GetRESTProxy()
ASSIGN proxy.ContentType = "application/json"
ASSIGN url = "https://catfact.ninja/fact"
ASSIGN verb = "GET"
ASSIGN result = proxy.MakeRestRequest(url,payload,'JSON',verb)

 

ASSIGN restProxy=GetRESTProxy()

restProxy.AddHeader("x-api-key", "qwer") //Assigning incorrect header for demonstration purposes
restProxy.ClearHeaders()
restProxy.AddHeader("x-api-key", "asdf")
ASSIGN restProxy.ProxyTimeoutSeconds = "2"
ASSIGN restProxy.ContentType = "application/json"

ASSIGN uri = "http://postman-echo.com/post"

DYNAMIC beowulfCharacteristics
ASSIGN beowulfCharacteristics.name = "Beowulf"
ASSIGN beowulfCharacteristics.occupation= "Hero" 
ASSIGN beowulfCharacteristics.foe = "Grendel"
ASSIGN payloadJSON = "{beowulfCharacteristics.asJSON()}

SNIPPETアクションでSOAP Webサービスに接続する

Studioスクリプトを使用して、SOAPベースのウェブサービスを使用できます。これには、WSDLまたはプロキシDLLをStudioインポートする必要があります。インポートされたDLLは、NICE CXoneによって承認されなければならない。DLLは承認後、CXoneシステムのファイルストレージのルートに保存されます。

SOAPウェブサービスを使用するには、NICE CXoneからの支援が必要です。詳細についてはCXoneアカウント担当者までお問い合わせください。

SOAPベースのウェブサービスをStudioスクリプトで使用する場合は、スニペットを作成する必要があります。Snippetアクションをスクリプトに追加します。Snippetエディターウィンドウで、生成してビジネスユニットのファイルストレージに格納したプロキシDLLファイルの名前を指定するUSESステートメントを追加します。

次のスニペットは、SOAPベースのWebサービスをStudioスクリプトで使用する例です:

USES "sf.dll"
cStart="{now}"
sforce=new SforceService()
session=new SessionHeader()
loginResult=sforce.login("demo@nice.com",password6")
sforce.sessionheadervalue=session
session.sessionid=loginResult.sessionid
sforce.url=loginresult.serverUrl

t=new Task()
t.ActivityDate=#"8/20/2050"
t.Description="Call placed by {first }{Last}."
t.Subject="Call @{cStart}"
t.Status="Completed"
t.CallType="Outbound"
t.OwnerId=SF_Agent_ID
t.ReminderDateTime="{cStart}"

SWITCH Type
{
   CASE "CON" { t.WhoId=SF_Obj_ID }
   CASE "LEA" { t.WhoId=SF_Obj_ID }
   CASE "ACC" { t.WhatId=SF_Obj_ID }
   CASE "OPP" { t.WhatId=SF_Obj_ID }
   CASE "CAS" { t.WhatId=SF_Obj_ID }
}
SaveResult=sforce.create(t)
	

RESTラッパーでSOAP呼び出しを行う

このオプションを使用すると、REST APIの手法を使用してSOAPベースのWebサービスを呼び出すことができます。どのWebサービスも、その構築方法によって応答が異なります。必要な場合、呼び出すサービスに合わせてサンプルコードを修正してください。

SNIPPETアクションで使用する場合、使用するXMLに二重引用符を含めることはできません。代わりに以下のいずれかの方法を使って接続できます。

  • 各二重引用符を{char(34)}で置き換えると、文字列に直接二重引用符が挿入されます。このオプションは、このセクションで後述するステップ2の最初の例に示されています。
  • 各二重引用符を一重引用符(')に置き換えます。これはXMLでもSNIPPETアクションでも使用できます。このオプションは、このセクションで後述するステップ2にある2つ目の例に示されています。

置き換える必要があるのはXMLに使われている二重引用符だけです。スニペットコード内の変数代入は、引き続き二重引用符で囲む必要があります。

  1. RESTプロキシを作成し、接続先のWebサービスが必要とするContentTypeヘッダーと、パブリックのWebサービスURLを割り当てます。

    ASSIGN RestProxy = GetRESTProxy() 
    ASSIGN RestProxy.ContentType = "text/xml; charset=utf-8"
    ASSIGN URL = "https://localhost:9031/ssodir/services/

    SSODirectoryService" //Assign the public Webservice UR
  2. 必要なパラメーターをすべてエンコードするXMLフォーマットのSOAPエンベロープを作成します。これは2つの方法で行うことができます。

    • 各行を区切る。この方法ではコードが読みやすくなります。

    • すべてを1行に連結する。

    このステップには両方のオプションの例が含まれています。

    この例では、エンベロープを行ごとに分けています。さらに、ここでは二重引用符が{char(34)}に置き換えてられています。

    //Sample Payload:
    ASSIGN Payload = ""
    ASSIGN Payload = "{Payload}<?xml version={char(34)}1.0{char(34)} encoding={char(34)}UTF-8{char(34)}?>
    ASSIGN Payload = "{Payload}<soapenv:Envelope"
    ASSIGN Payload = "{Payload}	xmlns:soapenv={char(34)}http://schemas.xmlsoap.org/soap/envelope/{char(34)}"
    ASSIGN Payload = "{Payload}	xmlns:xsd={char(34)}http://www.w3.org/2001/XMLSchema{char(34)}"
    ASSIGN Payload = "{Payload}	xmlns:xsi={char(34)}http://www.w3.org/2001/XMLSchema-instance{char(34)}>"
    ASSIGN Payload = "{Payload}<soapenv:Body>"
    ASSIGN Payload = "{Payload}<ns1:getIDPList"
    ASSIGN Payload = "{Payload}        soapenv:encodingStyle="
    ASSIGN Payload = "{Payload}	           {char(34)}http://schemas.xmlsoap.org/soap/encoding/{char(34)} ""
    ASSIGN Payload = "{Payload}xmlns:ns1="
    ASSIGN Payload = "{Payload}            {char(34)}https://localhost:9031/ssodir/services/"
    ASSIGN Payload = "{Payload}                 SSODirectoryService{char(34)}/>"
    ASSIGN Payload = "{Payload}</soapenv:Body>"
    ASSIGN Payload = "{Payload}</soapenv:Envelope>"

    次の例は、エンベロープコードを1行にまとめたものです。この例では、二重引用符が一重引用符に置き換えられています。

    //Sample Payload:
    ASSIGN Payload = "<?xml version='1.0' encoding='UTF-8'?><soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'><soapenv:Body><ns1:getIDPList soapenv:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' xmlns:ns1='https://localhost:9031/ssodir/services/SSODirectoryService'/> </soapenv:Body></soapenv:Envelope>"
    
  3. RESTリクエストを実行します。次の例は、POSTとして実行されています。

    Result = RestProxy.MakeRestRequest(URL,Payload,1,"POST")