使用 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 的重要概念就是資源。資源是具有類型 (例如商機 )、相關資料、與其他資源的關係，以及一組在其上操作的方法的物件。這些資源以階層方式組織，包括：
-
根資源：對應至邏輯物件，例如「機會」或「潛在客戶」。
-
子資源：這些是屬於上階資源的資源，例如機會的聯絡人。
-
值清單資源：設定欄位值時可使用的有效值清單。有兩種類型：「查閱」(靜態清單) 或「動態」(根據環境定義)。
在 Oracle Sales Automation RESTful API 中，有兩種資源類型：單一資源或集合資源。單一資源可以代表單一實體 (例如員工或採購單)，而收集資源可以更全面，例如員工清單或可分頁的採購單清單。
關於自訂物件的 REST 支援
Oracle Sales Automation 包含適用於許多業務需求與案例的標準物件。不過，除了標準物件之外，如果您有獨特的業務需求，可以使用「應用程式編寫器」工具來建立最上層自訂物件與下階自訂物件。
「應用程式編寫器」是一種瀏覽器型工具，業務分析師和管理員 (不只是開發人員) 可以用來自訂 Oracle Sales Automation 。透過使用此工具，您可以進行過去僅由開發人員進行的資料模型變更類型。在「應用程式編寫器」工具中，您可以即時進行變更，並立即可供使用而不需重新登入應用程式，這包括建立自訂物件 (可新增至 Oracle Sales Automation RESTful API)。
Performance Tips - 效能提示
若要從 Oracle Fusion Sales Cloud REST API 取得最佳效能，請遵循這些提示。
- 只查詢您需要的資料。
- 僅查詢資料，而非中繼資料。
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=true使用「描述」端點搜尋 RESTful 資源
您可以傳送傳回包含資源資訊和補充中繼資料的 JSON 物件的 HTTP GET 要求，以取得不同 Oracle Sales Automation RESTful API 的特定詳細資料。
取得 RESTful Web 服務的服務端點
您可以在 API URL 中指定服務名稱而非關鍵字 "describe"，來推斷 Oracle Sales Automation RESTful Web 服務端點的名稱。
關於 REST 作業與有效負載結構
每個標準 Oracle Sales Automation 物件的 RESTful Web 服務提供數個建立、讀取、更新及刪除 (CRUD) 作業。
您可以執行下列標準方法，透過單一資源或資源集合的 URL 與其互動：
| 方法 | 適用於單一資源 | 可用於資源集合 |
|---|---|---|
| 取得 | Y | N |
| 張貼 | N | Y |
| 修正程式 | Y | N |
| 刪除 | Y | N |
關於 Get 方法
使用此方法來查詢和擷取資訊。不過，查詢中用來縮小搜尋範圍或縮小單一資源結果範圍的參數，與資源集合中使用的參數不同。
單數與收帳資源的參數
方法中使用下列參數來查詢單一資源以及集合資源：
| Parameter - 參數 | 格式 | 描述 |
|---|---|---|
expand |
或
|
傳回包含其下階的上階資源。預設不會傳回任何子項。 |
fields |
fields=<FieldName1>,<FieldName2>... |
只選取其資訊為必要的某些欄位。 |
onlyData |
或
|
僅擷取資料，不擷取任何資源 URL。預設會傳回所有資源子項 URL。 |
收集資源的參數
收集資源的 GET 方法會使用上述參數以及下列參數：
| Parameter - 參數 | 格式 | 描述 |
|---|---|---|
limit |
|
大於 0 的整數，指定伺服器傳回的項目數上限。如果未指定限制值，伺服器將會使用預設的限制值。 |
offset |
offset=<Integer> |
整數值，指定第一個要傳回的項目索引。偏移索引從 0 開始。 |
q |
|
指定篩選條件以限制集合中傳回的項目。此查詢參數的值包含一或多個以 ";" 區隔的表示式。例如 支援的運算子：
特殊字元：
|
totalResults |
或
|
指定是否傳回符合 "q" 查詢參數之項目總數的布林值。
|
orderBy |
|
指定回應有效負載中傳回項目的順序。查詢參數值是欄位名稱的逗號分隔字串，每個字串會選擇性地後面跟著冒號和關鍵字 若未指定，伺服器會依遞增順序傳回項目。 |
finder |
|
使用具有專屬特殊參數的預先定義「查詢」。 例如， |
dependency |
|
用於串聯值清單資源。例如，如果 Location 資源有 State 欄位，這些值將衍生自另一個傳回特定「國家 / 地區 (位置)」之「州 / 省」清單的 States 資源。例如，位置為：美國，州為 CA。「州」資源包含所有「美國」的清單，但如果網頁中的使用者將地區設定變更為「巴西」，則擷取所有巴西州的方式會有如下的呼叫：
|
關於 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"
…
}關於修正方法
使用此方法對資源進行部分更新。只會更新要求主體中包含的欄位。
要求媒體類型為：
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: "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"
…
}關於刪除方法
使用此方法刪除資源。它不需要要求主體。
例如，若要從 Opportunities 資源刪除 Opportunity 物件，必須直接向要刪除之子項 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 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 回應物件會保留「結果」欄位中自訂動作方法的結果。
關於批次支援
為了提升效能，您可以將包含 "parts" 欄位的 JSON 物件作為物件陣列，將多個作業結合成單一 HTTP 要求。陣列中的每個物件都包含唯一的 ID、資源的相對路徑、作業，以及選擇性的有效負載 (Payload)。
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,
} ]}