42 RESTfulサービスを介したOracle Sales Cloudデータへのアクセス
各APIには、標準のOracle Sales Cloudオブジェクトが含まれており、各オブジェクトにはRESTリソースまたはリソース・コレクションが関連付けられています。たとえば、RESTful APIでは、ポテンシャル・セールスに関する情報を追跡するためにOpportunitiesリソース・エンドポイントが使用されます。ただし、Oracle Sales Cloud RESTful Webサービスを使用する前に、アクセスを確立するためのセキュリティ要件を考慮するだけでなく、使用するWebサービスとともに、対応するサポート対象のメソッドや予想されるペイロード構造も特定する必要があります。
Oracle Sales Cloud RESTful API内のリソースについて
Oracle Sales Cloudには、標準オブジェクトとカスタム・オブジェクト用のRESTリソースのコレクションが用意されています。
RESTful APIにおける重要なコンセプトは、リソースです。リソースとは、タイプ(Opportunitiesなど)、関連データ、他のリソースとの関係、およびリソースに対して動作する一連のメソッドを持つオブジェクトです。これらのリソースは、次が含まれる階層形式で編成されています。
-
ルート・リソース: 商談やリードなどの論理オブジェクトに対応しています。
-
サブリソース: これらは、親リソースに属するリリースです(たとえば、商談に対する担当者など)。
-
値リスト・リソース: フィールドに値を設定するときに使用できる有効な値のリスト。参照(静的リスト)または動的(コンテキスト・ベース)の2つのタイプがあります。
Oracle Sales Cloud RESTful APIには、単一リソースまたはコレクション・リソースという2つのタイプのリソースがあります。単一リソースは、従業員や購買オーダーなどの単一エンティティを表すことができます。一方、コレクション・リソースは、ページ付け可能な従業員のリストや購買オーダーのリストのように、より包括的である場合があります。
カスタム・オブジェクト用のRESTのサポートについて
Oracle Sales Cloudには、多くのビジネス・ニーズやシナリオに対応した標準オブジェクトがあります。ただし、独特のビジネス・ニーズがある場合は、標準オブジェクト以外にも、アプリケーション・コンポーザ・ツールを使用して、最上位のカスタム・オブジェクトと子カスタム・オブジェクトの両方を作成することができます。
アプリケーション・コンポーザは、(開発者のみでなく)ビジネス・アナリストや管理者がOracle Sales Cloudをカスタマイズするために使用できるブラウザ・ベースのツールです。このツールを使用することにより、以前は開発者によってのみ行われたデータ・モデルのタイプの変更を行うことができます。アプリケーション・コンポーザ・ツールでは、オンザフライ方式で変更を行うと、アプリケーションに再度サインインする必要なく、これらの変更が即時使用可能になります。これには、Oracle Sales Cloud RESTful APIに追加できるカスタム・オブジェクトの作成が含まれます。
describeエンドポイントを使用したRESTfulリソースの検索
様々なOracle Sales Cloud RESTful APIに関する特定の詳細は、リソース情報と補足メタデータが含まれるJSONオブジェクトを返すHTTP GETリクエストを送信することによって取得できます。
RESTful Webサービスのサービス・エンドポイントの取得
Oracle Sales Cloud RESTful Webサービス・エンドポイントの名前は、API URLでキーワードdescribeのかわりにサービス名を指定することによって推定できます。
REST操作およびペイロード構造について
標準の各Oracle Sales Cloudオブジェクト用のRESTful Webサービスには、複数の作成、読取り、更新および削除(CRUD)操作が用意されています。
URLを介して単一のリソースまたはリソース・コレクションと対話するために次の標準メソッドを実行できます。
| メソッド | 単一のリソースに使用可能 | リソース・コレクションに使用可能 |
|---|---|---|
| Get | Y | N |
| Post | N | Y |
| Patch | Y | N |
| Delete | Y | N |
Getメソッドについて
このメソッドを使用して、情報を問い合わせて取得します。ただし、単一のリソースで検索の微調整や結果の絞り込みのために問合せで使用するパラメータは、リソース・コレクションで使用するものとは異なります。
単一のリソースとコレクション・リソースの両方のパラメータ
単一のリソースとコレクション・リソースの問合せ用のメソッドでは、次のパラメータを使用します。
| パラメータ | 形式 | 説明 |
|---|---|---|
expand |
または
|
子を含む親リソースを返します。デフォルトでは、子を返しません。 |
fields |
fields=<FieldName1>,<FieldName2>... |
情報が必要とされる特定のフィールドのみを選択します。 |
onlyData |
または
|
データのみを取得し、リソースのURLは取得しません。デフォルトでは、すべてのリソースの子URLが返されます。 |
コレクション・リソースのパラメータ
コレクション・リソース用のGETメソッドは、上記のパラメータおよび次のパラメータを使用します。
| パラメータ | 形式 | 説明 |
|---|---|---|
limit |
|
サーバーによって返されるアイテムの最大数を指定する0より大きい整数。制限値が指定されない場合、サーバーはデフォルトの制限値を使用します。 |
offset |
offset=<Integer> |
返される最初のアイテムの索引を指定する整数値。オフセット索引は0から開始されます。 |
q |
|
コレクションで返されるアイテムを制限するフィルタ条件を指定します。この問合せパラメータの値には、「;」で区切られた1つ以上の式が含まれます。たとえば、 サポートされている演算子:
特殊文字:
|
totalResults |
または
|
q問合せパラメータと一致するアイテムの合計数を返すかどうかを指定するブール値。 |
orderBy |
|
レスポンス・ペイロードで返されるアイテムの順序を指定します。問合せパラメータ値は、カンマ区切りのフィールド名の文字列であり、オプションで各文字列の後ろにコロンおよびキーワード 指定しない場合、アイテムが昇順で返されます。 |
finder |
|
独自の特殊パラメータを持つ事前定義済の「問合せ」を使用します。 たとえば、 |
dependency |
|
カスケード値リスト・リソースに使用されます。たとえば、LocationリソースにStateフィールドがある場合、これらの値は、特定のCountry (場所)のStateのリストを返す別のStatesリソースから導出されます。たとえば、LocationがUS、StateがCAのような場合です。Statesリソースには、USのすべてのStatesのリストが含まれますが、Webページ内のユーザーがロケールをBrazilに変更した場合、ブラジルのすべての州を取得する方法は、次のようなコールを使用したものになります。
|
Postメソッドについて
このメソッドを使用して、新しいアイテムを作成します。リクエスト・メディア・タイプのヘッダーは、次のとおりです。
application/vnd.oracle.adf.resourceitem+json
たとえば、Opportunitiesリソースの下に新しい商談を作成するには、リクエストが新しい Opportunity名パラメータをJSONオブジェクトに渡します。
{ "Name" : "New Opportunity Name" }POSTリクエストから返されるJSONオブジェクトのレスポンス本体は、次のようになります。
{ BudgetAvailableDate: null BudgetedFlag: false PrimaryOrganizationId: 204 ChampionFlag: false CreatedBy: "SALES_ADMIN" CreationDate: "2015-06-04T03:08:27-07:00" CurrencyCode: "USD" SalesMethodId: 100000012430001 SalesStageId: 100000012430007 Name: "New Opportunity Name" OptyId: 300100111705686 OptyNumber: "CDRM_332708" OwnerResourcePartyId: 3807 StatusCode: "OPEN" PrimaryRevenueId: 300100111705687 SalesMethod: "Standard Sales Process" SalesStage: "01 - Qualification" DescriptionText: "Looking for the Right Contacts, Characteristics, Determining the Need, Budget and Sponsor" AverageDaysAtStage: 30 MaximumDaysInStage: 800 PhaseCd: "QUALIFICATION-DISCOVERY" QuotaFactor: 3 RcmndWinProb: 0 StageStatusCd: "OPEN" StgOrder: 1 EffectiveDate: "2015-06-24" Revenue: 0 WinProb: 0 PartyName1: "Charles Taylor" DownsideAmount: 0 UpsideAmount: 0 EmailAddress: "firstname lastname@orcl.com" ExpectAmount: 0 ForecastOverrideCode: "CRITERIA" SalesChannelCd: "ZPM_DIRECT_CHANNEL_TYPES" … }Patchメソッドについて
このメソッドを使用して、リソースの部分的な更新を行います。リクエス本体に含まれるフィールドのみが更新されます。
リクエスト・メディア・タイプは、次のとおりです。
application/vnd.oracle.adf.resourceitem+json
たとえば、既存の商談をOppurtunitiesリソースから更新するには、HTTP PATCHリクエストが次のJSONオブジェクトをリクエスト本体として渡します。
{ "Name": "Opportunity Name Updated" }このリクエストからのレスポンスは、次のようなJSONオブジェクトになります。
{ BudgetAvailableDate: null BudgetedFlag: false PrimaryOrganizationId: 204 ChampionFlag: false CreatedBy: "SALES_ADMIN" CreationDate: "2015-06-04T03:08:27-07:00" CurrencyCode: "USD" SalesMethodId: 100000012430001 SalesStageId: 100000012430007 Name: "New Opportunity Name" OptyId: 300100111705686 OptyNumber: "CDRM_332708" OwnerResourcePartyId: 3807 StatusCode: "OPEN" PrimaryRevenueId: 300100111705687 SalesMethod: "Standard Sales Process" SalesStage: "01 - Qualification" DescriptionText: "Looking for the Right Contacts, Characteristics, Determining the Need, Budget and Sponsor" AverageDaysAtStage: 30 MaximumDaysInStage: 800 PhaseCd: "QUALIFICATION-DISCOVERY" QuotaFactor: 3 RcmndWinProb: 0 StageStatusCd: "OPEN" StgOrder: 1 EffectiveDate: "2015-06-24" Revenue: 0 WinProb: 0 PartyName1: "Charles Taylor" DownsideAmount: 0 UpsideAmount: 0 EmailAddress: "firstname lastname@orcl.com" ExpectAmount: 0 ForecastOverrideCode: "CRITERIA" SalesChannelCd: "ZPM_DIRECT_CHANNEL_TYPES" … }Deleteメソッドについて
このメソッドを使用して、リソースを削除します。これには、リクエスト本体は必要ありません。
たとえば、Opportunitiesリソースから商談オブジェクトを削除するには、削除対象の子OpportunityリソースのURIに対して、パラメータを渡さずにDELETEリクエストを直接実行します。
https://<crm_server:PortNumber>/salesApi/resources/latest/opportunities/<OpportunityNumber>
カスタム・アクション・メソッドについて
場合によっては、CRUD標準に当てはまらないカスタム・アクションをリソースが公開します。カスタム・アクションは常に、(単一のリソースとリソース・コレクションの両方において) POSTを使用して起動され、そのリクエスト・メディア・タイプは次のとおりです。
application/vnd.oracle.adf.action+json
レスポンス・メディア・タイプは、次のとおりです。
application/vnd.oracle.adf.actionresult+json
たとえば、Oracle Sales Cloudでは、https://<crm_server:portNumber>/salesApi/resources/latest/describe/leads/の下のleadsリソースには、リードを商談に変換する、convertLeadToOptyと呼ばれるカスタム・アクションがあります。
{ "name" : "convertLeadToOpty", "parameters" : [ { "name" : "leadId", "type" : "number", "mandatory" : false } ], "resultType" : "string", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] },カスタム・アクションは、特定の目標を達成するための一連のステップ、プロセス、または各種CRUD操作の組合せであると考えてください。上記の例では、カスタム・アクションのリクエスト本体は、カスタム・アクション名(convertLeadToOpty)になるname、およびオプションでカスタム・アクションの入力パラメータの配列(leadId)を渡す必要があります。
通常、POSTリクエストのJSON本体には、次が含まれます。
{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "title": "Action execution representation.", "description": "Represents the action execution and its parameters.", "properties": { "name": { "type": "string", "description": "Action name."}, "parameters": { "type": "array", "description": "Parameter name/value pair.", } }, "required": [ "name" ] }JSONレスポンス・オブジェクトには、resultsフィールド内のカスタム・アクション・メソッドの結果が保持されています。
バッチ・サポートについて
パフォーマンスを向上させるために、partsという名前のフィールドが含まれるJSONオブジェクトをオブジェクトの配列として送信することにより、複数の操作を単一のHTTPリクエストに結合できます。配列内の各オブジェクトには、一意のID、リソースへの相対パス、操作、およびオプションのペイロードが含まれます。
HTTPリクエストのJSONスキーマは、次のとおりです。
{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "title": "Batch execution", "description": "Group multiple requests together ('part').", "definitions": { "Part": { "type": "object", "allOf": [ { "properties": { "id": { "type": "string", "description": "An identification provided by the client to distinguish each part provided in the batch request."}, "path": { "type": "string", "description": "Resource's location."}, "operation": { "type": "string", "enum": [ "get", "create", "update", "replace", "delete" ], "description": "The operation that will be performed."}, "preconditionSucceeded": { "type": "boolean", "description": "This attribute is set in the batch response only when ifMatch or ifNoneMatch are provided in the request.It will be 'true' if the precondition (ifMatch/ifNoneMatch) was satisfied, otherwise 'false'."}, "payload": { "oneOf": [ { "$ref": "resource-item.json", "description": "The payload that will be used in the operation.Example: a resource instance should be provided in order to execute a 'create'."}, { "type": "null" } ] } }, "required": [ "id", "path", "operation" ] } ], "anyOf": [ { "properties": { "ifMatch": { "type": "string", "description": "This attribute is analogous to the If-Match header.It represents a precondition to execute this operation.The value can be null (same effect of 'If- Match: *') or an array of resource versions."} } }, { "properties": { "ifNoneMatch": { "type": "string", "description": "This attribute is analogous to the If-None-Match header.It represents a precondition to execute this operation.The value can be null (same effect of 'If-None-Match: *') or an array of resource versions."} } } ], "description": "Represents a request."} }, "properties": { "parts": { "type": "array", "items": { "$ref": "#/definitions/Part" }, "description": "Array that represents multiple requests."} }, "required": [ "parts" ] }たとえば、次のリクエストの場合、既存の従業員をフェッチし、別の従業員を更新します。
POST /myapi/resources/latest/hremployees HTTP/1.1 Host: example.oracle.com Content-type:application/vnd.oracle.adf.batch+json { "parts": [ { "id": "part1", "path": "/latest/hremployees/101", "operation": "get" }, { "id": "part2", "path": "/latest/hremployees/102", "operation": "update", "payload": { "Salary": 18000 } } ] }以前のリクエストのレスポンスでは、リクエストと同じメディア・タイプを使用し、次のようなJSONオブジェクトを返します。
{"parts":[ { "id":"part1", "path":"/latest/hremployees/101", "operation":"get", "payload" : { "EmployeeId" : 101 … }, { "id" : "part2", "path" : "/latest/hremployees/102", "operation" : "update", "payload" : { "EmployeeId" : 102, } ]}