APIとスクリプト

Studioスクリプトでは、SOAPまたはRESTful API標準を使用するWebサービスに接続できます。

サポートされているオプション

Studioは、Webサービスへの以下の接続方法をサポートしています。

オプション	詳細
REST API Studioアクション	REST API Studioアクションを使用すると、スクリプトからRESTful APIを呼び出すことができます。この方法は、 SNIPPETアクションでRESTful呼び出しを行うよりも高い負荷を処理できます。 スクリプトでAPI呼び出しを行うための好ましい方法です。 呼び出しにJSONが含まれる場合に使用するオプションです。
CXone API Studioアクション	Studioには、スクリプトからCXone APIを呼び出すことができる数多くのAPIアクションが用意されています。すべてのCXone APIをアクションとして利用できるわけではありませんが、利用できる場合は、他の方法の代わりにそれを使用してください。APIアクションは、Desktop StudioのフレームワークタブのAPIセクションと、CXone StudioのAPIアクションパレットにあります。
SNIPPETアクション	SNIPPETアクションに、スクリプトからRESTfulまたはSOAP Webサービスに接続するコードを書くことができます。この方法は、REST呼び出しを行う際には、コンタクト対応が遅くなる可能性があるため推奨されません。ただし、以下の場合はこの方法を使用する必要があります。 呼び出しにXMLが含まれている。 SOAPサービスに接続している。

返されるデータサイズの制限

CXoneプラットフォームでは、REST APIは最大32 KBのデータを返すことができます。この制限により、クラスターの不安定や停止を防ぐことができます。これは厳格に強制されます。

この制限は、REST API アクションや、SNIPPETアクションでの呼び出しを含む、Webサービスへのあらゆる接続方法に適用されます。可能であれば、REST APIにはSNIPPETアクションの代わりにREST APIアクションを使用してください。REST APIで返されるデータは32 KBに制限されますが、SNIPPETメソッドよりも高い負荷を処理できます。

返されるデータのサイズを小さくするには：

• API応答のデータをフィルター処理します。 たとえば、NICEレポーティングAPIを使用してコンタクトを取得している場合、コンタクトのstartDateとendDateにより結果をフィルタリングできます。このAPIコールでは、アイテムのトップカウントを返したり制限したりすることもできます。どのようなフィルタリングを使用できるかを判断するには、スクリプト統合に付属のAPIドキュメントを参照してください。
• 必要なデータのみを返すようにAPIリクエストを更新します。 たとえば、NICEレポーティングAPIを使用してコンタクトを取得する場合、contactIdまたはagentIdのフィールドを使用して、関連するデータのみを返すことができます。呼び出すAPIのドキュメントを参照して、使用できるデータの制限を決定してください。

前のオプションのどちらも行うことができない場合は、ミドルウェアを構築します。

エラーコード「-1」

エラーコード「-1」は、API呼び出しでエラーが発生したことを識別するための内部コードです。具体的には、このコードはHTTPステータスコードが返されない、あるいは返されてもスクリプトに渡せない状況を示しています。

エラーコード「-1」に付随するステータスの説明は、問題を特定するのに役立ちます。このコードに付随するステータスの説明には、以下のようなものがあります。

• リクエストが中止されました。操作がタイムアウトしました。 リクエストが処理されたかどうかが不明です。検証は、ステータスコード「-1」に応答してループを設定する前に行ってください。必要な場合、ProxyTimeoutSecondsプロパティを使用して、呼び出しのタイムアウト設定を変更します。

• 無効なJSONプリミティブです。 JSONパーサーが応答に混乱しました。応答に無効な文字が含まれているか、JSONでない可能性があります。多くの場合、このエラーは応答がHTMLで送信される場合に発生します。スニペットデバッガーで応答をテストできます。REST API応答が有効なJSONまたはXMLではない場合の知識ベース記事が参考になります。

• ルートレベルのデータが無効です。 XMLパーサーが応答に混乱しました。応答に無効な文字が含まれているか、XMLでない可能性があります。多くの場合、このエラーは応答がHTMLで送信される場合に発生します。REST API応答が有効なJSONまたはXMLではない場合の知識ベース記事が参考になります。

• 'doctype'は予期しないトークンです。期待されるトークンは'DOCTYPE'です。このリストにある「ルートレベルのデータが無効です」を参照してください。

• 行xの位置xにある'br'開始タグが'body'の終了タグと一致しません。 このリストにある「ルートレベルのデータが無効です」を参照してください。

• 基盤の接続が閉じられました。送信時に予期しないエラーが発生しました。 多くの場合、これはTLSハンドシェイクに問題があることを意味します。また、ファイアウォールでIPまたはポートが開いていない、サポートされていない古いバージョンのTLSを使用している、無効または期限切れの証明書を使用している、HTTPSと組み合わせてIPアドレスを使用している、または同様の問題が原因の場合もあります。受信サーバー側のファイアウォールのログを使用して、この応答をトラブルシューティングしてください。

• 基盤の接続が閉じられました。SSL/TLSセキュアチャネルの信頼関係を確立できませんでした。 このリストにある「基盤の接続が閉じられました。送信時に予期しないエラーが発生しました。」を参照してください。

• リクエストが中止されました。SSL/TLSセキュアチャネルを作成できませんでした。 このリストにある「基盤の接続が閉じられました。送信時に予期しないエラーが発生しました。」を参照してください。

• 応答が大きすぎます。(> 32 KB)応答に32 KBを超えるデータが含まれています。このような場合、システムには1つの変数に32 KBより多くのデータを格納する方法がないため、応答は破棄されます。応答は、返されるデータ量を減らすために、修正またはフィルタリングを行う必要があります。

スクリプトとAPI