機械翻訳について
  1. Oracle Fusionサービスでのナレッジ管理のOKEC REST APIREST API
  2. クイック・スタート

クイック・スタート

Fusion Applications 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://servername.fa.us2.oraclecloud.com
  • ユーザー名とパスワード。 使用しているサービスにアクセスする権限を持つEngagement Cloudユーザー。

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

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

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

  1. リクエストURLを作成します。 URLは、サーバー名とリソース・パスで構成されます: 
    https://<server>/<resource-path>

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

    https://servername.fa.us2.oraclecloud.com

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

    /km/api/latest/content

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

    https://servername.fa.us2.oraclecloud.com/km/api/latest/content
  2. アカウント情報を指定します。 クライアントにユーザー名とパスワード(ステップ2から)を含めます。

たとえば、cURLを使用している場合は、次のように-uコマンドを使用してアカウント情報を指定できます: 

-u "username:password"

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

この図は、Postmanでの認可にBasic Authorizationを使用する方法を示しています。

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

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

ステップ4: 認証と承認

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

認証

ネットワークを介したデータ・アクセスがセキュアであることを確認するために、Fusion Applications REST APIでは、Multi Token Over SSL RESTful Service Policy (oracle/multi_token_over_ssl_rest_service_policy)というグローバルなOracle Web Services Manager (OWSM)セキュリティ・ポリシーを使用します。 このセキュリティ・ポリシーでは、次の認証標準が適用されます:

  • 「SSLを介した基本認証(Secure Socket Layer)」。「HTTPヘッダー」からユーザー名とパスワード資格証明を抽出します。

  • 「SSLを介したHTTPヘッダーのSAML 2.0 Bearerトークン」。SAML 2.0ベアラー・アサーション(XMLセキュリティ・トークン)を抽出します。

  • 「SSLを介したHTTPヘッダーのJWT」。JWTトークンからユーザー名を抽出します。

いずれかの標準を選択する必要があります。 SSLを介したBasic認証を使用した例を見てみましょう。 認証するには、Oracle Cloudアカウントのユーザー名とパスワードを送信する必要があります。 通常、ユーザー名とパスワードは、次のようにBase64形式でエンコードされます: 

curl -X POST https://servername.fa.us2.oraclecloud.com/km/api/latest/content 
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" 
-H "Accept: application/json" -H "Content-Type: application/json"

または、次の例のように、-u cURLオプションを使用して、Oracle Cloudアカウントのユーザー名とパスワードを渡すことができます: 

curl -X POST https://servername.fa.us2.oraclecloud.com/km/api/latest/content 
-u "username:password" -H "Accept: application/json" 
-H "Content-Type: application/json"

認可および認証情報がリクエスト・ヘッダーの認可キーで渡されます。 Postmanでトークン(SAMLまたはJWT)を渡す場合は、次のスクリーンショットに示すように、認可キーにBearerとトークンが含まれている必要があります:

この図は、Postmanクライアントで承認にBearerトークンを使用する方法を示しています。

承認

制限されたナレッジ情報にリポジトリからアクセスできるのは、適切な認可がある場合のみです。 ユーザーおよびロールの詳細は、「ナレッジ管理の使用」を参照してください。

ノート:

認証後、Fusion Serviceのナレッジのパブリック・ナレッジ・コンテンツおよびパブリックREST APIに、認可または匿名でアクセスできます。 REST APIおよびコンテンツに匿名でアクセスするには、認可ヘッダーなしでRESTリクエストを送信します。

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

完了までもう少しです。 認証および認可が設定されたので、テストHTTPリクエストを送信する準備ができました。 この例では、コンテンツ・リソースを使用して、2014年1月1日以降に公開されたドキュメントのリストを取得します。 これは、cURLのdescribeアクションを使用して実行できます: 

curl -X GET https://servername.fa.us2.oraclecloud.com/km/api/latest/content?limit=10&q=publishDate+after+%272014-04-01%27&mode=key 
-u "username:password" -H "Accept: application/json" 
-H "Content-Type: application/json"

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

この図は、PostmanでのGETリクエストの例を示しています。

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

{
"recordId": "048016517ab56ef014519740375005599",
"versionId": "048016517ab56ef01451974037500544f",
"documentId": "OR4",
"title": "Registration Now Open to the Public for Oracle OpenWorld San Francisco",
"version": "2.0",
"answerId": 1000077,
"links": [
{
"rel": "canonical",
"href": "https://<REST_API_HOST>/km/api/latest/content/048016517ab56ef014519740375005599",
"mediaType": "application/json, application/xml",
"method": "GET"
},
{
"rel": "collection",
"href": "https://<REST_API_HOST>/km/api/latest/content",
"mediaType": "application/json, application/xml",
"method": "GET",
"profile": "https://<REST_API_HOST>/km/api/latest/metadata-catalog/content"
}
]
}

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

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

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