Constellation DX API

重要なのは、DX APIには、次の2つのバージョンがあるということです。

• Constellation DX API
• 従来のDX API

Constellation DX APIは、ビューベースのオーサリングに重点を置いています。従来のDX APIでは、セクションベースのオーサリングが中心でした。 

Constellation DX APIは、いくつかの重要な点で、従来のDX APIとは異なります。

• まったく異なるJSON構造があり、データはビューのレイアウトと明確に分離されています。
• APIの呼び出し回数が減少します。
• 追加的なエンドポイントと共に、新機能が追加されました。たとえば、ケースをフォローまたはフォロー解除するためのエンドポイントや、ケースステージを変更するためのエンドポイントがあります。
• ハイパーメディアは、アプリケーション状態のエンジン（HATEOAS）です。その結果、回答は利用可能なアクションへの参照を提供します。
• Angular、React、Web Componentsなどの確立されたフレームワークと互換性のあるインタプリタがあらかじめ組み込まれています。

Constellation DX APIは、ハーネスやセクションの代わりに、App StudioとReactベースのビューオーサリングが中心となっており、Constellationアプリケーションにのみ使用します。

Constellation DX APIにリクエストを行う場合は、APIリクエストが、クライアントがサーバーからデータを取得するために送信するメッセージであることに注意してください。各リクエストには、メソッドとパスパラメーター、ヘッダー、クエリーパラメーター、および特定のAPIエンドポイントが要求するフィールドを含むリクエストボディを含めることができます。

パスパラメーター

パスパラメーターは、どのConstellation DX APIエンドポイントにアクセスするかを決定します。これは、APIコールから返される応答を決定します。

たとえば、GET /assignments/{id}/actions/{actionID}パスパラメーターは、ビューに関連する情報を含む、アサインメントの特定のフローアクションの詳細を返すリクエストです。

ヘッダー

HTTPヘッダーは、クライアントとサーバー間の接続を管理します。ヘッダーはキーと値のペアで構成され、リクエストに関するメタデータを伝えるためにHTTPメッセージに含まれます。Constellation DX APIは、次のヘッダーを使用します。

x-origin-channel 

x-origin-channelヘッダーは、リクエストの発信元を表します（例：ウェブ、モバイル）。これは、リクエストの発信元に基づいて、異なる処理を許可するルールの異なる状況を選択するために使用できます。一般的な例は、モバイルデバイスからのリクエストの場合、異なる画面サイズや向きに合わせてUIを自動的に拡大縮小するようにカスタマイズすることなどです。

if-matchおよびeTag 

if-matchと eTagは、楽観的ロック（複数のユーザーがレコードを更新する権限を持つ戦略）のために、組み合わせて使用されます。

eTagヘッダーはDX API応答に含まれ、現在のpxSaveDateTimeを表します。これは、特定のインスタンス（ケース、ワークアイテム、またはその他のデータオブジェクト）がシステムに最後に保存された日時を表すシステムプロパティです。 

ユーザーがリクエストを行った場合、応答のeTagヘッダーは、そのリソースが最後に更新された時刻を表しています。それ以降のリクエストでは、if-matchヘッダーは前のリクエストのeTagの値と共にリクエストに含まれています。これは、基本的に、リソースが前回のリクエスト以降に更新されていない場合にのみ、リソースの更新をリクエストする方法です。これにより、複数のユーザーが不注意に互いの変更を上書きしてしまうことを防ぐことができます。

言い換えれば、楽観的ロック戦略を採用する場合、アサインメント提出時にチェックが行われます。サービスからリソースが取得されると、応答ヘッダーでeTag値（ケースのpxSaveDateTime ）が送られます。ユーザーが送信するときには、前の応答で受け取ったeTag値をif-matchリクエストヘッダーとして渡す必要があります。このif-matchが現在のpxSaveDateTimeと一致した場合にのみ、ユーザーは更新操作を行うことができる。if-match値が現在のpxSaveDateTimeと一致しない場合、ユーザーはHTTP 409 Conflictエラーを受け取ります。

if-matchヘッダーは、すべてのアップデートに必須のヘッダーです。

注意点として、悲観的なロック戦略を採用している場合、あるユーザーによってケースがロックされると、他のユーザーは、ケースを開いてアサインメントの詳細を取得することができなくなります。代わりに、システムはHTTP 423 - resource lockedエラーを返します。

クエリーパラメーター

クエリーパラメーターは、リクエストのurlに追加情報を含める方法です。クエリーパラメーターは、クエスチョンマーク（?）の後のurlの末尾に付加され、アンパサンドシンボル（&）で区切られます。許可されるクエリーパラメーターは、各APIエンドポイントに固有のものです。Constellation DX APIの一般的なクエリーパラメーターには、viewTypeやpageNameなどがあります。

viewTypeクエリーパラメーターは、UIメタデータを返す量を指定し、次の値をサポートしています。

• ページ：すべてのウィジェットを含むフルページ
• フォーム：単なるアクションエリア
• フィールド：レイアウト情報のないフォームフィールド
• なし：ケースデータのみが返されます

pagenameクエリーパラメーターは、DX APIエンドポイントがアクセスできるビューページ名を指定します。

リクエストボディ

POST、PUT、またはPATCHメソッドを使用するリクエストは、リクエストボディを必要とします。リクエストボディには、サーバーがリソースを作成または更新するために必要な情報が含まれます。例：caseTypeID、parentCaseID、content、pageInstructions、attachments。

• caseTypeID 要素は、ケース作成時にのみ必要になります。
• parentCaseID要素は、ケース作成時にのみ必要となります。
• contentは、追加または更新されるプロパティのマップ表現（キーと値のペア）です。
• pageInstructions要素は、埋め込みページ、ページリスト、ページグループプロパティで実行されるページ関連操作のリストです。
• attachments要素は、添付ファイルのリストです。

サーバーは、APIに対する各クライアントのリクエストに応答して、関連するデータを送り返します。各APIエンドポイントは、一意のJSON応答を返します。各応答は一意ですが、Constellation DX APIの応答全体で共有されるプロパティがいくつかあります。

JSON応答には、4つの重要なトップレベルのプロパティ、data、uiResources, nextAssignmentInfo,、confirmationNoteがあります。

data

data には、ケースのステータス、利用可能なアクション、SLA情報、利用可能なステージのリストなどのケースの詳細、およびケースをルーティングしている担当者やオペレーターなど、ビューのフィールドで参照されるユーザーに関する情報が含まれています。

uiResources 

uiResources には、ページやフォームのレンダリングに必要なUIメタデータが含まれています。

nextAssignmentInfo

nextAssignmentInfo には、コンテキストやIDなど、次のアサインメントに関する情報が含まれています。nextAssignmentInfo プロパティは、現在のアサインメントの後に別のアサインメントが設定されている場合にのみ、応答に表示されます。

confirmationNote 

confirmationNote は、ケース処理中にエンドユーザーに表示されるメモです。confirmationNoteプロパティは、ケースの最後のステージでのみ表示されます。

エンドポイントの安全性を高めるため、Constellation DX APIでは、認証タイプとして常にOAuth 2.0を使用しています。

以下のインタラクションで理解度をチェックしてください。