Oracle Fusion Cloud ProcurementのREST API

クイック・スタート

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

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

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

ロールおよび権限を確認します。親および子リソースでGET、POST、PATCHおよびDELETEメソッドを使用するには、必要なセキュリティ・ロールおよび権限が必要です。詳細は、「共通機能のセキュリティ・リファレンス」を参照してください。

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

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

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

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

RESTサーバーURL。通常は、Oracle CloudサービスのURLです。たとえば、https://servername.fa.us2.oraclecloud.comです。
ユーザー名とパスワード。使用しているリソースにアクセスする権限を持つOracle Cloudサービス・ユーザー。

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

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

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

リクエスト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/procurementAgents
```
RESTサーバーURLを結合し、この例ではProcurement Agentsリソース・パスおよびリクエストURLが完了しました。詳細は、「REST APIのバージョンとURLパス」を参照してください。「REST APIのバージョンとURLパス」.
```
https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/procurementAgents 
```
Postmanなどのクライアントでは、この結合URLを「リクエストURL」フィールドに入力します。

ノート:
Visual Builder Studioを使用してREST APIにアクセスする場合は、「サービス仕様からのサービス接続の作成」を参照してください。 Oracle Integration Cloudを使用してREST APIにアクセスするには、「ドキュメントに記載されているMetadataを使用しないで外部REST APIを使用するためのRESTアダプタの構成」を参照してください。 RESTリソースにアクセスするための独自のクライアントを作成することもできます。 Javaプログラミング言語を使用してクライアントを構築するには、「JAX-RSクライアントAPIを使用したRESTリソースへのアクセス」を参照してください。
アカウント情報を指定します。クライアントにユーザー名とパスワード(ステップ2から)を含めます。たとえば、cURLを使用している場合は、次のように-u cURLコマンドを使用してアカウント情報を指定できます:
```
-u <username:password>
```
Postmanなどのクライアントでは、Authorizationタブでユーザー名とパスワードを入力します。次のスクリーンショットは、Postmanで次の情報を指定する方法を示しています:

また、サーバーの適切な承認タイプ(basicなど)を選択する必要があります。詳細は、ステップ4を参照してください。
メディア・タイプを設定します。メディア・タイプは、サーバーとクライアント間で交換される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/procurementAgents/describe \
 -H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'  | json_pp

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

ビジネス要件に応じて、REST APIの動作を微調整するために、「RESTフレームワークの設定」または「Cross-Origin Resource Sharingの構成」を今すぐ実行する場合があります。それ以外の場合は、ステップ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 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/procurementAgents/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/procurementAgents/describe \
-H 'Content-Type: application/vnd.oracle.adf.resourceitem+json'

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

承認

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

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

権限
Procurement Cloudのセキュリティ・リファレンス
共通機能のセキュリティ・リファレンス
Oracle ERP Cloud ERPの保護: Oracle Procurementのセキュリティ

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

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

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

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

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


{
    "Resources": {
        "procurementAgents": {
            "discrColumnType": false,
            "attributes": [
                {
                    "name": "AssignmentId",
                    "type": "integer",
                    "updatable": true,
                    "mandatory": true,
                    "queryable": true,
                    "allowChanges": "inCreate",
                    "precision": 18,
                    "hasDefaultValueExpression": true
                },
                {
                    "name": "Agent",
                    "type": "string",
                    "updatable": true,
                    "mandatory": false,
                    "queryable": true,
                    "allowChanges": "never",
                    "precision": 240,
                    "title": "Name",
                    "maxLength": "240",
                    "properties": {
                        "DISPLAYWIDTH": "30"
                    },                
					...
            "links": [
                {
                    "rel": "self",
                    "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/procurementAgents/describe",
                    "name": "self",
                    "kind": "describe"
                },
                {
                    "rel": "canonical",
                    "href": "https://servername.fa.us2.oraclecloud.com/fscmRestApi/resources/11.13.18.05/procurementAgents/describe",
                    "name": "canonical",
                    "kind": "describe"
                }
            ]
        }
    }
}

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

ノート:

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

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

一般的なプロセスについては、「ユースケース」セクションで学習します。
「詳細」セクションを確認して「コレクション」の管理を改善するか、「バッチ処理」を作成して実行します。
「Oracle Developerコミュニティ」に参加して、ヒントやアドバイスを他のユーザーと共有できます。