Redwoodユーザー・エクスペリエンスによるナレッジ管理のREST API

クイック・スタート

Oracle Applications Cloud REST APIを使用して、様々なタイプのHTTPリクエストを作成できます。コンテンツ・レコードの表示、作成、更新または削除を容易にリクエストできます。例として、コンテンツ・リソースに指定された日付より後に公開されたドキュメントのリストを検索して取得するための単純なREST HTTPリクエストを送信する方法を見てみましょう。

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

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

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

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

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

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

RESTサーバーURL。通常、これはOracle CloudサービスのURLです。例:https://<FA POD name>.apps.us.ocs.oraclecloud.com
ユーザー名とパスワード。使用しているサービスにアクセスする権限を持つEngagement Cloudユーザー。

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

ステップ3: リクエストURLの作成

URLは、サーバー名とリソース・パスで構成されます:

https://<server>/<resource-path>

次のように、<server>はステップ2のRESTサーバーURLです:

https://<FA POD name>.apps.us.ocs.oraclecloud.com

<resource-path>は、作業中のリソースの相対パスまたは「エンドポイント」です。「すべてのRESTエンドポイント」で任意のエンドポイントを選択できます。この例では、articleリソースに関心があります。

api/knowledge-management/v2/articles

RESTサーバーURLを組み合せます。この例では、コンテンツ・リソース・パスとリクエストURLが完成しています。詳細は、「URLパス」を参照してください。

https://<FA POD name>.apps.us.ocs.oraclecloud.com/api/knowledge-management/v2/articles

ビジネス要件に応じて、REST APIの動作を微調整するために、「Cross-Origin Resource Sharing (CORS)の構成」を今すぐ実行することをお薦めします。それ以外の場合は、ステップ4に進みます。

ステップ4: 認証と承認

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

サード・パーティ・クライアントまたは独自のカスタム・クライアントを使用して、これらの新しいREST APIにアクセスできます。ただし、アイデンティティ・サービス・プロバイダからOAuthトークンが必要になります。 Oracle Identity Cloud Service (IDCS)またはOracle Cloud Infrastructure Identity and Access Management (OCI IAM)サービスを使用している場合は、Oracle IDCSにクライアントを機密アプリケーションとして登録する必要があります。

機密アプリケーションの追加、クライアントの構成、認証および認可の詳細は、次を参照してください: 機密アプリケーションの追加、Oracle Cloudアイデンティティ・サービスの管理ガイド。

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

任意のクライアント、またはPostmanやcURLなどのサードパーティ・クライアントを使用して、アクセス・トークンを取得し、それを渡して必要なリソースにアクセスできます。

例: cURLを使用したリソースへのアクセス

cURLリクエストは次のとおりです:

curl -H "Authorization: Bearer Token" \
-X GET https://servername.apps.us.ocs.oraclecloud.com/api/knowledge-management/v2/articles
-H 'Content-Type: application/json'

リクエストが成功すると、本文付きでスペースを節約するために省略されたレスポンスを受け取ります。リクエストが失敗し、cURLを使用している場合は、レスポンス・コメントを確認し、リクエストを調整してから再試行してください。他のクライアントを使用している場合は、障害「ステータス・コード」を確認してから再試行してください。

{
            "recordId": "9285C4D829CD468AB39C49907A1ED3E4",
            "versionId": "A14CCD4BB3404281939635ABEA458ECB",
            "documentId": "AUTO1",
            "title": "Document with attachment updated123.",
            "version": "2.0",
            "answerId": 10027037,
            "dateModified": "2022-04-25T16:32:21.000+00:00",
            "displayStartDate": "1900-01-01T00:00:00.000+00:00",
            "displayEndDate": "9999-12-31T00:00:00.000+00:00",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://servername.apps.us.ocs.oraclecloud.com/api/knowledge-management/v2/articles/9285C4D829CD468AB39C49907A1ED3E4",
                    "mediaType": "application/json, application/xml",
                    "method": "GET"
                },
                {
                    "rel": "collection",
                    "href": "https://servername.apps.us.ocs.oraclecloud.com/api/knowledge-management/v2/articles",
                    "mediaType": "application/json, application/xml",
                    "method": "GET"
                }
            ],
            "versionState": "LIVE",
            "createDate": "2022-04-25T15:06:17.000+00:00",
            "lastModifiedDate": "2022-04-25T15:06:17.000+00:00",
            "dateAdded": "2022-04-25T16:32:20.000+00:00",
            "published": true,
            "pending": false,
            "publishDate": "2022-04-25T16:32:20.000+00:00",
            "checkedOut": false,
            "publishedVersion": "2.0",
            "isForEdit": false
        },
        {
            "recordId": "2F33BD8C1D9246B9970D0D098C2BA17F",
            "versionId": "FFC350D9AA7E40D58A664E38FC1E2751",
            "documentId": "FAQ212",
            "title": "Registration now open for Oracle OpenWorld.",
            "version": "2.0",
            "answerId": 10027036,
            "dateModified": "2022-04-25T19:53:22.000+00:00",
            "displayStartDate": "1900-01-01T00:00:00.000+00:00",
            "displayEndDate": "9999-12-31T00:00:00.000+00:00",
            "links": [
                {
                    "rel": "canonical",
                    "href": "https://servername.apps.us.ocs.oraclecloud.com/api/knowledge-management/v2/articles/2F33BD8C1D9246B9970D0D098C2BA17F",
                    "mediaType": "application/json, application/xml",
                    "method": "GET"
                },
                {
                    "rel": "collection",
                    "href": "https://servername.apps.us.ocs.oraclecloud.com/api/knowledge-management/v2/articles",
                    "mediaType": "application/json, application/xml",
                    "method": "GET"
                }

例: Postmanを使用したリソースへのアクセス

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

Postmanでは、結果は書式設定され、レスポンス・セクションに表示されます。レスポンスは複数の形式で表示できます。このスクリーンショットは、JSONでのレスポンスを示しています。

この図は、JSON形式のレスポンス本文がinPostmanにどのように表示されるかを示しています。

おめでとうございます! REST APIをさらに活用する準備が整いました。「Oracle Developerコミュニティ」に参加して、ヒントやアドバイスを他のユーザーと共有できます。