使用 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 的自定义对象。
性能提示
要从 Oracle Fusion Sales Cloud REST API 中获得卓越性能，请遵循以下提示。
- 仅查询所需的数据。
- 仅查询数据，而不查询元数据。
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=true使用“描述”端点搜索 RESTful 资源
您可以通过发送 HTTP GET 请求来获取有关不同 Oracle Sales Automation RESTful API 的特定详细信息，该请求返回包含资源信息和补充元数据的 JSON 对象。
获取 RESTful Web 服务的服务端点
您可以通过在 API URL 中指定服务名称而不是关键字“描述”来推断 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 资源，该资源返回特定国家（地区）的状态列表。例如，如果位置为：US，State 为 CA。States 资源包含所有美国州的列表，但是如果网页中的用户将语言环境更改为 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"
…
}关于补丁程序方法
使用此方法对资源进行部分更新。将仅更新请求正文中包含的字段。
请求介质类型为：
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 响应对象在“结果”字段中保存 custom action 方法的结果。
关于批量支持
为了提高性能，可以通过发送包含名为“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,
} ]}