APIとスクリプト

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

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

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

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

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

CXone Mpowerプラットフォームでは、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セキュアチャネルを作成できませんでした。 このリストにある「基盤の接続が閉じられました。送信時に予期しないエラーが発生しました。」を参照してください。
応答が大きすぎます。（32KB未満） 応答に32KBを超えるデータが含まれています。このような場合、システムには1つの変数に32 KBより多くのデータを格納する方法がないため、応答は破棄されます。応答は、返されるデータ量を減らすために、修正またはフィルタリングを行う必要があります。