機械翻訳について
  1. REST APIスタート・ガイドV4REST API for Common Features in Oracle Fusion Cloud Applications
  2. クイック・スタート

クイック・スタート

Oracle Fusion Cloud Applications REST APIを使用して、様々なタイプのHTTPリクエストを作成できます。 レコードの表示、作成、更新または削除リクエストを簡単に実行できます。 たとえば、簡単なREST HTTPリクエストを送信して、お知らせオブジェクトの構造を確認する方法を見てみましょう。

ノート:

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

    この例では、お知らせリソースまたはその属性に関心があり、これに関連付けられている機能をオプトインする必要があります。

    /fscmRestApi/resources/11.13.18.05/announcements

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

    https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/announcements

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

    https://<servername>/api/boss/data/objects/<module segments>/v1/$openapi/<resource>

    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などのクライアントでは、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/fscmRestApi/resources/11.13.18.05/announcements/describe \
 -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'  | json_pp

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

ビジネス要件に応じて、ここで「RESTフレームワークの設定」または「Cross-Origin Resource Sharing (CORS)の構成」を使用して、REST APIの動作を微調整できます。 それ以外の場合は、ステップ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リソースを使用するには、サポートされているアイデンティティ・サービス・プロバイダ、Oracle Identity Cloud Service (IDCS)またはOracle Identity Access Management (IAM)のOAuthトークンが必要です。 機密アプリケーションの追加、クライアント、認証および認可の構成の詳細は、Oracle Cloudアイデンティティ・サービスの管理ガイドのトピック「機密アプリケーションの追加」を参照してください。

いずれかの標準を選択する必要があります。 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/fscmRestApi/resources/11.13.18.05/announcements/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/fscmRestApi/resources/11.13.18.05/announcements/describe \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

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

承認および認証情報の渡し

認可

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

リソースにアクセスするための特定のロールのリストなどの詳細は、「共通機能のセキュリティ・リファレンス」を参照してください。

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

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

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

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

Postmanでのリクエストの例

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

{
    "Resources": {
        "announcements": {
            "discrColumnType": false,
            "attributes": [
                {
                    "name": "AnnouncementId",
                    "type": "string",
                    "updatable": true,
                    "mandatory": true,
                    "queryable": true,
                    "allowChanges": "inCreate",
                    "precision": 18,
                    "hasDefaultValueExpression": true
                },
                ...
            ],
            "collection": {
                "rangeSize": 25,
                "finders": [
                    {
                        "name": "PrimaryKey",
                        "attributes": [
                            {
                                "name": "AnnouncementId",
                                "type": "string",
                                "updatable": true,
                                "mandatory": true,
                                "queryable": true,
                                "allowChanges": "inCreate",
                                "precision": 18,
                                "hasDefaultValueExpression": true
                            }
                        ]
                    }
                ],
                "links": [
                    {
                        "rel": "self",
                        "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/announcements",
                        "name": "self",
                        "kind": "collection"
                    }
                ],
                "actions": [
                    {
                        "name": "get",
                        "method": "GET",
                        "responseType": [
                            "application/vnd.oracle.adf.resourcecollection+json",
                            "application/json"
                        ]
                    },
                    {
                        "name": "create",
                        "method": "POST",
                        "requestType": [
                            "application/vnd.oracle.adf.resourceitem+json",
                            "application/json"
                        ],
                        "responseType": [
                            "application/vnd.oracle.adf.resourceitem+json",
                            "application/json"
                        ]
                    },
                    {
                        "name": "upsert",
                        "header": "Upsert-Mode=true",
                        "method": "POST",
                        "requestType": [
                            "application/vnd.oracle.adf.resourceitem+json",
                            "application/json"
                        ],
                        "responseType": [
                            "application/vnd.oracle.adf.resourceitem+json",
                            "application/json"
                        ]
                    }
                ]
            },
            "item": {
                "links": [
                    {
                        "rel": "self",
                        "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/announcements/{id}",
                        "name": "self",
                        "kind": "item"
                    },
                    {
                        "rel": "canonical",
                        "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/announcements/{id}",
                        "name": "canonical",
                        "kind": "item"
                    },
                    {
                        "rel": "enclosure",
                        "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/announcements/enclosure/DescriptionClob",
                        "name": "DescriptionClob",
                        "kind": "other"
                    }
                ],
                "actions": [
                    {
                        "name": "get",
                        "method": "GET",
                        "responseType": [
                            "application/vnd.oracle.adf.resourceitem+json",
                            "application/json"
                        ]
                    },
                    {
                        "name": "update",
                        "method": "PATCH",
                        "requestType": [
                            "application/vnd.oracle.adf.resourceitem+json",
                            "application/json"
                        ],
                        "responseType": [
                            "application/vnd.oracle.adf.resourceitem+json",
                            "application/json"
                        ]
                    },
                    {
                        "name": "delete",
                        "method": "DELETE"
                    }
                ]
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/announcements/describe",
                    "name": "self",
                    "kind": "describe"
                },
                {
                    "rel": "canonical",
                    "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/announcements/describe",
                    "name": "canonical",
                    "kind": "describe"
                }
            ]
        }
    }
}

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

Postmanでのレスポンスの例

ノート:

自動生成された一意の識別子とユーザー定義識別子の両方を使用してエンティティ関係(外部キー)を公開するリソースを操作する場合、いずれかのCRUDアクションでリクエスト・ペイロードでこれらのパラメータの1つのみを使用する必要があります。 両方を含める場合、動作は指定されず、予告なしに変更される可能性があります。 これを理解するために、calendarEventリソースにお知らせリソースへの外部キーが含まれているとします。 お知らせリソースに一意の識別子AnnouncementId (300100111705686)と、AnnouncementNumber (ANN_332708)という代替ユーザー定義識別子があるとします。 新しいcalendarEventを作成するか、またはcalendarEventのお知らせへの参照を更新する場合、リクエスト・ペイロードにAnnouncementIdパラメータとAnnouncementNumberパラメータの両方を含めることはできません。

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