Getting Started With the API

概要

このガイドは、CXone Mpower Expert APIを利用して、外部システムとの連携、ワークフローの自動化、分析データの取得を行うための導入手順を説明します。

なぜAPIが必要なのか？

CXone Mpower Expertは「タッチポイント（Touchpoints）」という形で、CRMや他のWebアプリケーションとの連携が容易な機能を提供しています。
しかし、Expert APIは画面表示を必要としないシステム、例えば音声アシスタントやIoTデバイスとの連携も可能です。
さらに、以下のような用途での利用も想定されます：

コンテンツ公開の自動化システムとの統合
ユーザー管理システムとの連携
翻訳管理システムとの接続

これらの高度な連携には、プログラミングスキルとある程度のシステム設計が求められますが、APIを活用することで、組織全体にわたる機能拡張が可能になります。

技術的な構成

APIはRESTに準拠しており、Expertサイトの /@api/deki に配置されています。

例：https://example.com/@api/deki

サイト内のあらゆるリソース（ページ、ユーザー、グループなど）にAPI経由でアクセス可能です。認証済みのユーザーは、ブラウザからAPIにアクセスできます。システム連携やアプリケーション連携にはAPIトークンが必要です。

HTTPS

API通信はHTTPSによって保護されています。クライアント（ブラウザなど）は、APIドメインおよび必要な追加ドメインを信頼する必要があります。

統合に必要なドメイン：

*.cloudfront.net
files.mtstatic.com

SSL/TLS証明書の更新に備え、ドメイン単位ではなく、認証局（CA）のルート証明書および中間証明書を信頼することが推奨されます。

レスポンス形式

デフォルトでは application/xml; charset=utf-8 が返されますが、クエリパラメータ dream.out.format=json を付与すると application/json; charset=utf-8 形式で取得可能です。

例：

XML → https://example.com/@api/deki/pages/{id}/info
JSON → https://example.com/@api/deki/pages/{id}/info?dream.out.format=json

一部のエンドポイントでは、デフォルトでJSONが返ることがあります。

ステータスコード

APIのレスポンスには標準的なHTTPステータスコードが使われています。

ステータス	意味
200 OK	正常に処理されました
201 Accepted	リクエストは受理され、キューで処理待ちです
203 Non-Authoritative Info	一部不完全なデータを含むレスポンス
301 Moved Permanently	エンドポイントが新しいURLに移動しました
302 Found	リソースが別のURLに存在します
400 Bad Request	リクエストパラメータが不正または不足
401 Unauthorized	認証失敗
403 Forbidden	権限不足または不正な認証情報
404 Not Found	リソースが存在しません
405 Not Allowed	HTTPメソッドがサポートされていません
410 Gone	廃止されたエンドポイントで代替なし

エラー形式

エラーは以下2種類のフォーマットで返される可能性があります。統合側では両方に対応する必要があります。

現在の標準形式：

<error>
  <exception>{exception}</exception>
  <message>{message}</message>
</error>

旧形式（非推奨）：

<error>
  <status>{status}</status>
  <title>{title}</title>
  <message>{message}</message>
  <uri>{uri}</uri>
</error>

各要素の説明：

{exception}: エラーを識別するユニークキー
{message}: 問題の内容や説明
{status}: HTTPステータスコード
{title}: HTTPステータス名
{uri}: 問題が発生したAPIエンドポイントのURL

認証とトークンの種類

APIでは以下の3種類のトークンでアクセス制御を行います：

Auth Token（認証トークン）
サインイン後にブラウザのクッキーとして設定される暗号署名付きトークン。改ざん防止機能付き。
Browser API Token
JavaScriptなど、ブラウザ上で実行されるアプリケーションからのAPIアクセス用。
CORSを活用して、信頼されたドメインにのみアクセスを許可。
権限はブラウザセッション中の authtoken に依存。未サインイン状態では匿名ユーザーとして扱われる。
Server API Token
C#、Java、Node.js、Python、PHPなどで実装されたサーバーアプリケーション、IoT、ボット等との連携に使用。
key と secret による署名で安全な通信が可能。secret は漏洩防止のため厳重管理が必要。
OAuth API Token
第三者開発者との連携に適した業界標準の認可フロー。
アクセス許可の範囲をユーザーが明示的に制御可能。管理者権限を渡す必要がないため安全性が高い。

この内容で正しい「Getting Started With the API」セクションを翻訳済みです。
次のセクション（例：コアリソースやエンドポイント）へ続けてもよろしいでしょうか？

CXone Mpower Expert APIの使い始めにあたって

概要