Oracle FusionサービスでのチャットのREST API

クイック・スタート

Fusion Applications APIを使用して、様々なタイプのHTTPリクエストを作成できます。情報を表示、作成、更新または削除するリクエストを簡単に実行できます。そのため、最初にREST HTTPリクエストを送信してチャット・エンゲージメントを作成します。

ステップ1: 開始する前に考慮

基本を確認します。 REST APIを初めて使用する場合は、RESTとJSONの基本を理解し、「重要な用語」のリストをスキャンしてください。

ロールおよび権限のレビュー: 親および子リソースでGET、POST、PATCHおよびDELETEメソッドを使用するには、必要なセキュリティ・ロールおよび権限が必要です。

オプトイン要件を確認します。属性の一部のリソースは、使用する前にオプトインが必要な機能に関連付けることができます。開始する前に、オプトイン機能を有効にする必要があります。

RESTクライアントを選択します。 REST APIは、HTTPプロトコルを介してソフトウェア・プログラムに接続します。 HTTPリクエストを送信するには、ソフトウェア・クライアントが必要です。この例では、cURLを使用します。ただし、cURLは、使用できる唯一のツールではありません。いずれかを選択するには、「RESTクライアントの操作」を参照してください。

ステップ2: Fusion Applicationsアカウント情報の取得

REST HTTP要求を行うには、いくつかの情報を収集する必要があります。

RESTサーバーURL。 chatAuthenticateエンドポイントがホストされているサーバー。たとえば:
```
https://servername.fa.us2.oraclecloud.com
```
ユーザー名とパスワード。 chatAuthenticateエンドポイントにアクセスする権限を持つOracle Cloudサービス・ユーザー。

RESTサーバーURL、ユーザー名およびパスワードは、Oracle Cloudサービス管理者に送信されたようこそ電子メールに記載されています。

ステップ3: 認証

チャット・エンゲージメントを作成するには、認証用のJSON Webトークン(JWT)が必要です。チャット・エンゲージメントを作成するには、このJWTをベアラー認可ヘッダーとしてリクエストに指定する必要があります。

このJWTを確認するには、Basic Authorizationヘッダーを使用してEngagement CloudのchatAuthenticateエンドポイントを起動し、(ステップ2から)資格証明を指定します。 JWTは、chatAuthenticateコールのレスポンスで返されます。 chatAuthenticateエンドポイントの詳細は、「チャット認証について」を参照してください。

chatAuthenticateレスポンスは、チャット・エンゲージメントの作成リクエストに必要な次の値も返します:

Domain. Oracle Fusionサービス・チャット・サービスのドメインURL。たとえば、https://chat_rest_server_domain.comです。
サイト名 chatAuthenticateコールのレスポンスで返されたサイトの完全修飾名。
Port. ポート値が返されるのは、ポートが80や443などのデフォルト・ポートでない場合のみです。
プールID。サイトに構成されているプールID。プールIDは、チャット・サービスが実行されているクラスタのIDを示します。 Oracleでは、スケジュール/スケジュール外のメンテナンス中にプールIDを変更できます。

chatAuthenticateをコールしてJWTを取得するcURLコマンドは次のとおりです:

curl -X POST "https://servername.fa.us2.oraclecloud.com/serviceApi/resources/11.13.0.0/chatAuthenticate" -H "Accept: application/json" -H "Accept-Language: en_US" -H "Authorization: Basic ZGNzYWRtaW4xOldlbGNvbWUx" -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" -d "{\"clientType\" : \"CONSUMER\",\"authUserName\" : \"John Smith\",\"categoryId\" : null,\"contactId\" : null,\"emailAddress\" : \"john.smith@vision.com\",\"firstName\" : \"John\",\"lastName\" : \"Smith\",\"incidentId\" : null,\"organizationId\" : null,\"productId\" : null,\"question\" : \"Question\",\"queueId\" : \"2\",\"interfaceId\": \"1\",\"resumeType\": \"RESUME\",\"incidentName\": \"TestIncident\",\"incidentType\": \"SVC_SERVICE_REQUESTS\",\"inventoryItemId\": null,\"inventoryOrgId\": null,\"prodGroupId\": null,\"businessUnitOrgId\" : null}"

ノート:

ユーザー名とパスワードは、Base64形式でエンコードされ、前述の例に示すように、cURLコマンドのBasic Authorizationヘッダーを使用して指定されます。または、 -u cURLオプションを使用して、ユーザー名とパスワードを渡すこともできます。構文は-u username:passwordです。
ユーザー・メタデータは、cURLコマンドの -dオプションを使用して指定されます。

PostmanなどのREST APIクライアントで、Authorizationタブにユーザー名とパスワードを入力します。次のスクリーンショットは、Postmanで次の情報を指定する方法を示しています:

認証が成功すると、JWT、ドメイン、サイト名、ポートおよびプールIDがレスポンスに次のように返されます:

{
    "authUserName": "John Smith",
    "categoryId": null,
    "chatSiteName": "sdi_11_20_18_2022_21-3586727808788512-Fusion",
    "clientType": "CONSUMER",
    "contactId": null,
    "domain": "chat_rest_server_domain.com",
    "emailAddress": "john.smith@vision.com",
    "firstName": "John",
    "incidentId": null,
    "interfaceId": "1",
    "jwt": "eyJhbGciOiJSUz...tr0Cw5qyvZMd64fyCA",
    "lastName": "Smith",
    "organizationId": null,
    "poolId": "353:2",
    "productId": null,
    "question": "Question",
    "queueId": "2",
    "resumeType": "RESUME",
    "incidentName": "TestIncident",
    "incidentType": "SVC_SERVICE_REQUESTS",
    "inventoryItemId": null,
    "inventoryOrgId": null,
    "prodGroupId": null,
    "mediaList": null,
    "businessUnitOrgId": null
    "links": [
        {
            "rel": "self",
            "href": "https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.0.0/chatAuthenticate/John%20Smith",
            "name": "chatAuthenticate",
            "kind": "item"
        },
        {
            "rel": "canonical",
            "href": "https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.0.0/chatAuthenticate/John%20Smith",
            "name": "chatAuthenticate",
            "kind": "item"
        }
    ]
}

ステップ4: クライアントの構成

これまでに収集された情報を使用して、REST HTTPリクエストを送信するようにクライアントを構成する準備が整います。

リクエストURLを作成します。 URLは、ドメイン名およびエンドポイント・パスで構成されます:
```
https://<domain>/<endpoint-path>
```
次のように、<domain>はステップ3のRESTサーバー・ドメインです:
```
https://chat_rest_server_domain.com
```
<endpoint-path>は、作業しているRESTエンドポイントへの相対パスです。「すべてのRESTエンドポイント」で任意のエンドポイントを選択できます。たとえば、requestEngagementエンドポイントに関心があります:
```
/engagement/api/consumer/{fqSiteName}/v1/requestEngagement
```
ここで、fqSiteName値は、ステップ3で決定された'sdi_11_20_18_2022_21-3586727808788512-Fusion'です。

ドメイン名とこの例では、requestEngagement RESTエンドポイント・パスとリクエストURLが完成しています。詳細は、「URLパス」を参照してください。
```
https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/requestEngagement
```
HTTP動詞を確認します。 HTTP動詞は、実行するCRUD操作のタイプによって異なります。この場合、チャット・エンゲージメントを作成するため、HTTP動詞はPOSTになります。
メディア・タイプを設定します。メディア・タイプは、サーバーとクライアント間で交換されるHTTPペイロードの構造を定義します。 cURLを使用している場合は、「ヘッダー」 -Hオプションを使用してメディア・タイプを指定できます。この場合、POSTリクエストであるため、メディア・タイプはapplication/jsonになります。メディア・タイプの詳細は、「サポートされているメディア・タイプ」を参照してください。
リクエスト本文を指定します。 -dオプションを使用して、次のようにリクエスト本文を指定します:
```
-d "{\"clientRequestTime\" : \"2019-01-14T14:35:14.226Z\",\"clientTransactionId\" : 1}"
```

プールIDを指定します。次のように、(ステップ3の)プールID値を含めます:

https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/requestEngagement?pool=353:2

完了すると、完全なcURLコマンドは次のようになります:

curl -X POST "https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/requestEngagement?pool=353:2" -H "Accept: application/json;charset=utf-8" -H "Content-Type: application/json;charset=utf-8" -d "{\"clientRequestTime\" : \"2019-01-14T14:35:14.226Z\",\"clientTransactionId\" : 1}"

例で使用されている構文に精通していない場合は、「RESTクライアントの操作」を確認してください。

高度なRESTユーザーですが、クイック・スタートを読み取っている場合は、ここで「Cross-Origin Resource Sharingの構成」を使用できます。それ以外の場合は、ステップ5に進みます。

ステップ5: 承認

完全なリクエストURLでクライアントを構成し、認証JWTをフェッチしたので、認可に進むことができます。認証は資格証明が本物であることを証明しますが、認可によってアクセス権限を適用できます。

チャット・エンゲージメントを作成するために認可されたアクセスを取得するには、次のように、Bearer Authorizationヘッダーを使用して、ステップ3のJWTをリクエストに含める必要があります:

curl -X POST "https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/requestEngagement?pool=353:2" -H "Accept: application/json;charset=utf-8" -H "Authorization: Bearer eyJhbGciOiJSUz...tr0Cw5qyvZMd64fyCA" -H "Content-Type: application/json;charset=utf-8" -d "{\"clientRequestTime\" : \"2019-01-14T14:35:14.226Z\",\"clientTransactionId\" : 1}"

Postmanなどのクライアントでは、JWTをBearer認可ヘッダーとして指定します。次のスクリーンショットは、Postmanで次の情報を指定する方法を示しています:

ステップ6: HTTPリクエストの送信

完了までもう少しです。認証および認可が設定されたので、テストHTTPリクエストを送信する準備ができました。この例を続けて、チャット・エンゲージメントを作成します。これは、cURLの次のコマンドを使用して実行できます:

curl -X POST "https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/requestEngagement?pool=353:2" -H "Accept: application/json;charset=utf-8" -H "Authorization: Bearer eyJhbGciOiJSUz...tr0Cw5qyvZMd64fyCA" -H "Content-Type: application/json;charset=utf-8" -d "{\"clientRequestTime\" : \"2019-01-14T14:35:14.226Z\",\"clientTransactionId\" : 1}"

リクエストはPostmanで次のように表示されます:

チャット・エンゲージメントの作成リクエストが成功した場合、次の例のような本文を含むレスポンスを受け取ります。リクエストが失敗し、cURLを使用している場合は、レスポンス・コメントを確認し、リクエストを調整してから再試行してください。他のクライアントを使用している場合は、障害「ステータス・コード」を確認してから再試行してください。

{
    "engagementId": 226,
    "engagementIdString": "226",
    "cancelledSurveyId": 0,
    "cancelledSurveyIdString": "0",
    "completedSurveyId": 0,
    "completedSurveyIdString": "0",
    "cancelledSurveyAuth": "",
    "completedSurveyAuth": "",
    "resultType": "SUCCESS",
    "sessionId": "170c233dfi4gy1vkwyw6yxdq1a",
    "sneakPreviewState": "DISABLED",
    "sneakPreviewInterval": 3000,
    "clientRequestTime": "2019-01-14T14:35:14.226Z",
    "clientTransactionId": 1,
    "clientTransactionIdString": "1",
    "serviceStartTime": "2019-01-11T10:12:13.175Z",
    "serviceFinishTime": "2019-01-11T10:12:13.298Z",
    "clientId": 246,
    "clientIdString": "246"
}

Postmanなどのクライアントでは、結果が書式設定され、レスポンス・セクションに表示されます。たとえば、Postmanを使用すると、複数の形式で出力を表示できます。このスクリーンショットは、JSONでのレスポンスを示しています。

おめでとうございます! REST APIをさらに活用する準備が整いました。

「詳細」セクションを確認して、より高度な概念を理解します。
「Oracle Developerコミュニティ」に参加して、ヒントやアドバイスを他のユーザーと共有できます。