RESTfulサービスを使用したOracle Sales Automationデータへのアクセス
各APIには、標準のOracle Sales Automationオブジェクトが含まれており、各オブジェクトはRESTリソースまたはリソース・コレクションに関連付けられています。たとえば、RESTful APIでは、潜在的な販売に関する情報を追跡するためにOpportunitiesリソース・エンドポイントが使用されます。ただし、Oracle Sales Automation RESTful Webサービスを使用する前に、アクセスを取得するためのセキュリティ要件を考慮し、使用するWebサービスとともに、対応するサポート対象のメソッドや予想されるペイロード構造も特定する必要があります。
Oracle Sales Automation RESTful API内のリソースについて
Oracle Sales Automationには、標準オブジェクトとカスタム・オブジェクト用のRESTリソースのコレクションが用意されています。
RESTful APIにおける重要なコンセプトは、リソースです。リソースとは、タイプ(「商談」など)、関連データ、他のリソースとの関係、およびリソースに対して動作する一連のメソッドを持つオブジェクトです。これらのリソースは、次が含まれる階層形式で編成されています。
-
ルート・リソース: 商談やリードなどの論理オブジェクトに対応しています。
-
サブリソース: これらは、親リソースに属するリソースです(たとえば、商談の担当者など)。
-
値リスト・リソース: フィールドの値の設定時に使用できる有効な値のリスト。参照(静的リスト)または動的(コンテキスト・ベース)の2つのタイプがあります。
Oracle Sales Automation RESTful APIには、単一リソースまたはコレクション・リソースという2つのタイプのリソースがあります。単一リソースは、従業員や購買オーダーなどの単一エンティティを表すことができます。一方、コレクション・リソースは、ページ付け可能な従業員のリストや購買オーダーのリストのように、より包括的なものにできます。
カスタム・オブジェクト用のRESTのサポートについて
Oracle Sales Automationには、多くのビジネス・ニーズやシナリオに対応する標準オブジェクトがあります。ただし、一意のビジネス・ニーズがある場合は、標準オブジェクト以外にも、アプリケーション・コンポーザ・ツールを使用して、最上位のカスタム・オブジェクトと子カスタム・オブジェクトの両方を作成できます。
アプリケーション・コンポーザは、(開発者だけでなく)ビジネス・アナリストや管理者がOracle Sales Automationをカスタマイズするために使用できるブラウザ・ベースのツールです。このツールを使用することにより、以前は開発者によってのみ行われたデータ・モデルのタイプの変更を行うことができます。アプリケーション・コンポーザ・ツールでは、オンザフライ方式で変更を行うと、アプリケーションに再度サインインする必要なく、これらの変更が即時使用可能になります。これには、Oracle Sales Automation RESTful APIに追加できるカスタム・オブジェクトの作成が含まれます。
パフォーマンス上のヒント
Oracle Fusion Sales Cloud REST APIから最高のパフォーマンスを得るには、次のヒントに従います。
- 必要なデータのみを問い合せます。
- メタデータではなく、データのみを問い合せます。
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=truedescribeエンドポイントを使用したRESTfulリソースの検索
様々なOracle Sales Automation RESTful APIに関する特定の詳細は、リソース情報および補足メタデータを含むJSONオブジェクトを返すHTTP GETリクエストを送信することによって取得できます。
RESTful Webサービスのサービス・エンドポイントの取得
Oracle Sales Automation RESTful Webサービス・エンドポイントの名前は、API URLでキーワードdescribeのかわりにサービス名を指定することによって推測できます。
REST操作およびペイロード構造について
標準のOracle Sales AutomationオブジェクトごとにRESTful Webサービスには、複数の作成、読取り、更新および削除(CRUD)操作が用意されています。
URLを介して単一のリソースまたはリソース・コレクションと対話するために次の標準メソッドを実行できます。
| Method | 単一のリソースに使用できます | リソース・コレクションに使用できます |
|---|---|---|
| 取得 | はい | N |
| 転記 | N | はい |
| パッチ | はい | N |
| 削除 | はい | 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フィールドがある場合、これらの値は、特定の国(場所)の州のリストを返す別のStatesリソースから導出されます。たとえば、LocationがUS、StateがCAのようになります。Statesリソースには、すべてのUS Statesのリストが含まれますが、Webページ内のユーザーがロケールをBrazilに変更した場合、ブラジルのすべての州を取得する方法は、次のようなコールを使用したものになります。
|
Postメソッドについて
このメソッドを使用して、新しいアイテムを作成します。リクエスト・メディア・タイプのヘッダーは、次のとおりです。
application/vnd.oracle.adf.resourceitem+jsonたとえば、Opportunitiesリソースの下に新しい商談を作成するには、リクエストが新しい「商談」名パラメータを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リソースから既存のOpportunityを更新するには、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: "Opportunity Name Updated"
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オブジェクトを削除するには、DELETEリクエストを、パラメータを渡すことなく、削除される子OpportunityリソースのURIに直接実行する必要があります。
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 Automationでは、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,
} ]}