機械翻訳について
  1. Oracle Fusion Cloud Customer ExperienceのOracle CX SalesおよびB2B Service REST API for Sales and Fusion ServiceのREST API
  2. クイック・スタート

クイック・スタート

Oracle Fusion Cloud Applications REST APIを使用して、様々なタイプのHTTPリクエストを作成できます。 レコードの表示、作成、更新または削除リクエストを簡単に実行できます。 例として、商談オブジェクトの構造を確認するための単純なREST HTTPリクエストを送信する方法を見てみましょう。 このトピックでは、このタスクのcURLステップとPostmanステップの両方について説明します。

ノート:

一部のRESTリソースには複数のバージョンがあります。 タスク・セクションで、複数のバージョンを持つリソースを展開すると、メイン・フォルダに、使用可能なリソース・バージョンに対応する11.13.18.05やv1 (最新)などのサブフォルダが含まれていることがわかります。 サブフォルダ11.13.18.05にはリソースの古いバージョンが含まれ、サブフォルダv1には同じリソースの最新バージョンが含まれます。 11.13.18.05バージョンを持たないリソースには、唯一のリソース・フォルダとしてv1フォルダがあります。 新しいバージョンがないリソースは、フォルダ構造を変更せずに引き続き表示されます。

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

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

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

リソースにアクセスするための特定のロールのリストなどの詳細は、次を参照してください:

オプトイン要件を確認します。 一部のRESTリソースまたはその属性は、使用する前にオプトインが必要な機能に関連付けられている場合があります。 開始する前に、オプトイン機能を有効にする必要があります。

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

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

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

  • RESTサーバーURL。 通常は、Oracle CloudサービスのURLです。 たとえば、https://servername.fa.us2.oraclecloud.comです。

  • ユーザー名とパスワード。 使用しているリソースにアクセスする権限を持つOracle 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エンドポイント」で任意のエンドポイントを選択できます。 ただし、一部のリソースまたはその属性は、使用する前にオプトインが必要な機能に関連付けられている場合があります。 この例では、Opportunitiesリソースまたはその属性に関心があり、これに関連付けられている機能をオプトインする必要があります。 どの機能が企業にオプトインされているかを実装マネージャに尋ねます。 

    /crmRestApi/resources/11.13.18.05/opportunities

    同じリソースにv1バージョンもある場合、URLパスの形式は若干異なります:

    https://<servername>/api/boss/data/objects/<module segments>/v1/<service name>

    RESTサーバーURLを結合し、この例では、商談リソース・パスとリクエストURLが完了します。 詳細は、「REST APIのバージョンとURLパス」を参照してください。 

    https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities

    Postmanなどのクライアントでは、この結合URLを「リクエストURL」フィールドに入力します。

    ノート:

    Visual Builder Studioを使用してREST APIにアクセスする場合は、「サービス仕様からのサービス接続の作成」を参照してください。 Oracle Integration Cloudを使用してREST APIにアクセスするには、「ドキュメントに記載されているMetadataを使用しないで外部REST APIを使用するためのRESTアダプタの構成」を参照してください。 RESTリソースにアクセスするための独自のクライアントを作成することもできます。 Javaプログラミング言語を使用してクライアントを構築するには、「JAX-RSクライアントAPIを使用したRESTリソースへのアクセス」を参照してください。

  2. アカウント情報を指定します。 クライアントにユーザー名とパスワード(ステップ2から)を含めます。 たとえば、cURLを使用している場合は、次のように-u cURLコマンドを使用してアカウント情報を指定できます: 

    -u <username:password>

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

    Basic認証、ユーザー名およびパスワードを使用したPostmanの例。

    また、サーバーの適切な承認タイプ(basicなど)を選択する必要があります。 詳細は、ステップ4を参照してください。

  3. メディア・タイプを設定します。 メディア・タイプは、サーバーとクライアント間で交換されるHTTPペイロードの構造を定義します。 たとえば、cURLを使用している場合は、次のように「ヘッダー」 -Hコマンドを使用してリソース・アイテム・メディア・タイプを指定できます: 

    -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

    リクエスト本文(POSTやPATCHなど)を持つリクエストの場合は、Content-Typeリクエスト・ヘッダーを含める必要があります。 メディア・タイプの詳細は、「サポートされるメディア・タイプ」を参照してください。

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

curl -u <username:password> \
 -X GET https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/describe  \
 -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'  | json_pp
REST APIクライアントでは、ヘッダー情報の一部としてメディア・タイプを含めます。 たとえば、Postmanでは、メディア・タイプをContent-Typeキーまたはヘッダーとして、次のような適切な値で渡すことができます 
application/vnd.oracle.adf.resourceitem+json
ヘッダーには複数のメディア・タイプを指定できます。

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

ビジネス要件に応じて、REST APIの動作を微調整するために、「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トークンからユーザー名を抽出します。

  • トークン・ベースの認証および認可の場合は、OAuth 2.0。 v1リソースを使用するには、アイデンティティ・サービス・プロバイダからのOAuthトークンが必要です。

いずれかの標準を選択する必要があります。 SSLを介したBasic認証を使用した例を見てみましょう。

ノート:

Oracle REST APIはSSL/TLS 1.3バージョンをサポートしています。 Transport Layer Security (TLS)を使用すると、クライアントとサーバーは保護されたレイヤーを介して通信できます。この場合、データは、関係者のみが認識する暗号化された形式で転送されます。 TLSは、様々なキー交換メソッドおよびデータ暗号化をサポートし、メッセージの整合性を認証します。

認証するには、Oracle Cloudアカウントのユーザー名とパスワードを送信する必要があります。 通常、ユーザー名とパスワードは、次のように「Base64形式」でエンコードされます: 

curl \
-X GET https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/describe  \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

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

curl -u username:password \
-X GET https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/describe \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

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

認可キーおよびトークンを使用したPostmanの例。

承認

承認では、サービス・ロール別にアクセス権限が強制されます。 オブジェクトへのアクセスによって、リソースへのアクセスが決まります。 そのため、ユーザーのロールが適切であることを確認してください。

リソースにアクセスするための特定のロールのリストなどの詳細は、次を参照してください:

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

完了までもう少しです。 認証および認可が設定されたので、テストHTTPリクエストを送信する準備ができました。 この例に続いて、RESTのOpportunitiesオブジェクトの構造に関するすべての情報を取得します。 これは、cURLのdescribeアクションを使用して実行できます: 

curl -u username:password \
 -X GET https://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/describe \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

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

リクエストのあるPostmanの例。

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


{
"Resources": {
"opportunities": {
"discrColumnType": false,
"title": "Opportunity",
"titlePlural": "Opportunities",
"attributes": [
	{
		"name": "BudgetAvailableDate",
        "type": "date",
        "updatable": true,
        "mandatory": false,
        "queryable": false,
        "allowChanges": "always",
        "title": "Date Budget Available",
        "annotations": {...}
		},
		...
},
],
"collection": {
"rangeSize": 25,
"finders": [
	{
		"name": "MyOpportunitiesFinder",
        "title": "My Open Opportunities",
        "attributes": [
    {
        "name": "ClosePeriod",
        "type": "string",
        "updatable": true,
        "required": "Optional",
        "queryable": false,
        "allowChanges": "always"
        }
		],
		},
		...
},
],
"item": {
"links": [
	{
        "rel": "lov",
        "href": "http://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/{id}/lov/YesNoLOV",
        "name": "YesNoLOV",
        "kind": "collection"
     },
     {
        "rel": "lov",
        "href": "http://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/{id}/lov/BusinessUnitPVO",
        "name": "BusinessUnitPVO",
        "kind": "collection"
      },
	  ...
},
],
"annotations": {
"description": "An opportunity is used by a sales organization to track information about a potential sale such as the sales account, key contacts, product interests, and potential revenues.",
"children": [
	{
        "name": "ChildRevenue",
        "description": "Revenue items on the opportunity."
     },
	 ...
},
],
"children": {
"Assessments": {
"discrColumnType": false,
"attributes": [
	{
        "name": "AssessmentId",
        "type": "integer",
        "updatable": true,
        "mandatory": true,
        "queryable": true,
        "allowChanges": "always",
        "precision": 18,
        "hasDefaultValueExpression": true,
        "properties": {
        "FIELDORDER": "1.0"
        }
     },
	 ...
},
],
 "links": [
	{
        "rel": "self",
        "href": "http://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/describe",
        "name": "self",
        "kind": "describe"
    },
    {
        "rel": "canonical",
        "href": "http://servername.fa.us2.oraclecloud.com/crmRestApi/resources/11.13.18.05/opportunities/describe",
        "name": "canonical",
        "kind": "describe"
    },
	...
},
],
}

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

JSONのレスポンスを持つPostmanの例。

ノート:

自動生成された一意IDとユーザー定義キーの両方を公開するリソースでの作業中に、リクエスト・ペイロードのパラメータの1つのみをCRUDアクションに使用する必要があります。 たとえば、商談リソースには、一意の識別子OptyIdと、OptyNumberという代替ユーザー定義キーがあります。 リソース・レベルまたはそのいずれかの子のデータを更新する場合、同じリクエスト・ペイロードでOptyIdパラメータとOptyNumberパラメータの両方を使用することはお薦めしません。 リクエストが同じレコードに解決されない場合があります。

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