RESTful 서비스를 사용하여 Oracle Sales Automation 데이터 액세스
각 API에는 표준 Oracle Sales Automation 객체가 포함되며 각 객체는 REST 자원 또는 자원 수집과 연계됩니다. 예를 들어, RESTful API에서 Opportunities 리소스 끝점은 잠재적 판매 정보를 추적하는 데 사용됩니다. 그러나 Oracle Sales Automation RESTful 웹 서비스를 사용하기 전에 접근 권한을 얻기 위한 보안 요구사항을 고려하고, 사용할 웹 서비스를 해당 지원 방법 및 예상 페이로드 구조와 함께 식별해야 합니다.
Oracle Sales Automation RESTful API의 리소스 정보
Oracle Sales Automation은 표준 및 사용자정의 객체에 대한 REST 리소스 모음을 제공합니다.
RESTful API에서 중요한 개념은 리소스입니다. 리소스는 유형(예: 기회), 연관된 데이터, 다른 리소스에 대한 관계 및 해당 리소스에 대해 작동하는 일련의 메소드를 가진 객체입니다. 이러한 리소스는 다음을 포함하는 계층적 방식으로 구성됩니다.
-
루트 리소스: Opportunity 또는 Lead와 같은 논리적 객체에 해당합니다.
-
하위 자원: 상위 자원(예: 기회에 대한 담당자)에 속하는 자원입니다.
-
값 목록 리소스: 필드에 대한 값을 설정할 때 사용할 수 있는 유효한 값 목록입니다. 조회(정적 목록) 또는 동적(컨텍스트 기반)의 두 가지 유형이 있습니다.
Oracle Sales Automation RESTful API에는 두 가지 유형의 자원(단일 자원 또는 수집 자원)이 있습니다. 단일 자원은 사원이나 구매 발주와 같은 단일 개체를 나타낼 수 있으며, 수집 자원은 사원 목록이나 페이징할 수 있는 구매 발주 목록과 같이 보다 포괄적입니다.
사용자정의 객체에 대한 REST 지원 정보
Oracle Sales Automation에는 많은 비즈니스 요구사항 및 시나리오를 고려하는 표준 객체가 포함되어 있습니다. 그러나 업무에 고유한 요구 사항이 있는 경우 표준 객체 외에도 Application Composer 툴을 사용하여 최상위 사용자정의 객체와 하위 사용자정의 객체를 모두 생성할 수 있습니다.
Application Composer는 비즈니스 분석가와 관리자(개발자만이 아님)가 Oracle Sales Automation을 사용자정의하는 데 사용할 수 있는 브라우저 기반 도구입니다. 이 도구를 사용하면 과거에는 개발자에 의해서만 변경된 데이터 모델 유형을 변경할 수 있습니다. Application Composer 툴에서 즉시 변경할 수 있으며 애플리케이션에 다시 사인인하지 않고도 즉시 사용할 수 있게 됩니다. 여기에는 Oracle Sales Automation RESTful API에 추가할 수 있는 사용자정의 객체 생성이 포함됩니다.
성능 참고 사항
Oracle Fusion Sales Cloud REST API에서 최고의 성능을 얻으려면 다음 팁을 따르십시오.
- 필요한 데이터만 query합니다.
- 메타데이터가 아닌 데이터만 쿼리합니다.
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=true"설명" 끝점을 사용하여 RESTful 리소스 검색
리소스 정보 및 보완 메타데이터를 포함하는 JSON 객체를 반환하는 HTTP GET 요청을 전송하여 여러 Oracle Sales Automation RESTful API에 대한 특정 세부정보를 확인할 수 있습니다.
RESTful 웹 서비스에 대한 서비스 끝점을 가져옵니다.
API URL에 "describe" 키워드 대신 서비스 이름을 지정하여 Oracle Sales Automation RESTful 웹 서비스 엔드포인트의 이름을 추론할 수 있습니다.
REST 작업 및 페이로드 구조 정보
각 표준 Oracle Sales Automation 객체에 대한 RESTful 웹 서비스는 여러 CRUD(생성, 읽기, 업데이트 및 삭제) 작업을 제공합니다.
URL을 통해 단일 리소스 또는 리소스 모음과 상호 작용하기 위해 다음과 같은 표준 메소드를 실행할 수 있습니다.
| 메소드 | 단일 자원에 사용가능 | 리소스 수집에 사용 가능 |
|---|---|---|
| 가져오기 | Y | N |
| 게시 | N | Y |
| 패치 | Y | N |
| 삭제 | Y | N |
가져오기 메소드 정보
이 메소드를 사용하여 정보를 질의하고 검색합니다. 그러나 단일 리소스에서 검색을 세분화하거나 결과를 좁히기 위해 질의에 사용되는 매개변수는 리소스 수집에 사용되는 매개변수와 다릅니다.
단일 및 수집 자원 모두에 대한 매개변수
다음 매개변수는 단일 리소스 및 수집 리소스를 질의하는 메소드에 사용됩니다.
| 매개변수 | 형식 | 설명 |
|---|---|---|
expand |
또는
|
해당 하위를 포함하여 상위 리소스를 반환합니다. 기본적으로 하위 항목을 반환하지 않습니다. |
fields |
fields=<FieldName1>,<FieldName2>... |
정보가 필요한 특정 필드만 선택합니다. |
onlyData |
또는
|
리소스 URL이 아닌 데이터만 검색합니다. 기본적으로 모든 리소스 하위 URL이 반환됩니다. |
회수 자원 매개변수
컬렉션 리소스에 대한 GET 메소드는 위에서 설명한 매개변수와 다음 매개변수를 사용합니다.
| 매개변수 | 형식 | 설명 |
|---|---|---|
limit |
|
서버에서 반환되는 최대 항목 수를 지정하는 0보다 큰 정수입니다. 지정된 제한 값이 없을 경우 서버는 기본 제한 값을 사용합니다. |
offset |
offset=<Integer> |
반환할 첫 번째 항목의 인덱스를 지정하는 정수 값입니다. 오프셋 인덱스는 0부터 시작합니다. |
q |
|
컬렉션에 반환되는 항목을 제한하는 필터 조건을 지정합니다. 이 질의 매개변수의 값에는 ";"으로 구분된 표현식이 하나 이상 포함되어 있습니다. 예: 지원되는 연산자:
특수 문자:
|
totalResults |
또는
|
"q" 질의 매개변수와 일치하는 총 항목 수를 반환할지 여부를 지정하는 부울 값입니다.
|
orderBy |
|
응답 페이로드에서 반환되는 항목의 순서를 지정합니다. 질의 매개변수 값은 쉼표로 구분된 필드 이름 문자열로, 선택적으로 뒤에 콜론과 키워드 지정되지 않은 경우 서버는 항목을 오름차순으로 반환합니다. |
finder |
|
고유의 특수 매개변수가 있는 미리 정의된 "질의"를 사용합니다. 예를 들어, |
dependency |
|
값 목록 리소스에 사용됩니다. 예를 들어, Location 리소스에 State 필드가 있는 경우 해당 값은 특정 국가(위치)에 대한 상태 목록을 반환하는 다른 States 리소스에서 파생됩니다. 예를 들어 Location이 US이고 State가 CA인 경우 States 리소스에는 모든 미국 주 목록이 포함되어 있지만 웹 페이지의 사용자가 로케일을 브라질로 변경하면 모든 브라질 주를 검색하는 방법은 다음과 같습니다.
|
게시 방법 정보
이 방법을 사용하여 새 항목을 생성합니다. 요청 매체 유형 헤더는 다음과 같습니다.
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 리소스에서 기존 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"
…
}삭제 방법 정보
이 방법을 사용하여 리소스를 삭제합니다. 요청 본문이 필요하지 않습니다.
예를 들어, 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 응답 객체는 "결과" 필드에 사용자정의 작업 메소드의 결과를 보유합니다.
뱃치 지원 정보
성능 향상을 위해 "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"
]
}
예를 들어, 다음 요청은 기존 사원을 패치(fetch)하고 다른 사원을 갱신합니다.
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,
} ]}