Accesso ai dati di Oracle Sales Automation mediante i servizi RESTful
Ogni API contiene oggetti Oracle Sales Automation standard e ogni oggetto è associato a una risorsa o a una raccolta risorse REST. Ad esempio, nell'API RESTful l'endpoint risorsa Opportunities viene utilizzato per tenere traccia delle informazioni su una vendita potenziale. Tuttavia, prima di utilizzare i servizi Web Oracle Sales Automation RESTful è necessario tenere conto dei requisiti di sicurezza per l'accesso e identificare anche i servizi Web da utilizzare, insieme ai metodi supportati corrispondenti e alle strutture payload previste.
Informazioni sulle risorse nelle API Oracle Sales Automation RESTful
Oracle Sales Automation fornisce una raccolta di risorse REST per oggetti standard e personalizzati.
Un concetto importante in qualsiasi API RESTful è la risorsa. Una risorsa è un oggetto con un tipo (ad esempio, Opportunità), dati associati, relazioni con altre risorse e un set di metodi che vi operano. Queste risorse sono organizzate in modo gerarchico e comprendono:
-
Risorsa radice: corrisponde a un oggetto logico, ad esempio un'opportunità o un lead.
-
Risorse secondarie: si tratta di risorse che appartengono a una risorsa padre, ad esempio un contatto per un'opportunità.
-
Risorsa elenco di valori: elenco di valori validi che è possibile utilizzare quando si imposta un valore per un campo. Esistono due tipi: Ricerca (elenco statico) o Dinamico (in base al contesto).
Nell'API Oracle Sales Automation RESTful sono disponibili due tipi di risorse: una singola risorsa o una risorsa di raccolta. Una singola risorsa può rappresentare una singola entità, ad esempio un dipendente o un ordine di acquisto, mentre una risorsa di riscossione può essere più completa, ad esempio un elenco di dipendenti o un elenco di ordini di acquisto di cui è possibile eseguire il paging.
Informazioni sul supporto REST per gli oggetti personalizzati
Oracle Sales Automation include oggetti standard che tengono conto di molte esigenze e scenari aziendali. Tuttavia, oltre agli oggetti standard, è possibile utilizzare lo strumento Creazione applicazione per creare sia oggetti personalizzati di livello superiore che oggetti personalizzati figlio se si ha un'esigenza aziendale univoca.
Application Composer è uno strumento basato su browser che gli analisti aziendali e gli amministratori (non solo gli sviluppatori) possono utilizzare per personalizzare Oracle Sales Automation. Utilizzando questo strumento, è possibile apportare i tipi di modifiche al modello dati che in passato sono state apportate solo dagli sviluppatori. Lo strumento Creazione applicazioni consente di apportare modifiche in tempo reale e diventano immediatamente disponibili per l'uso senza dover accedere di nuovo all'applicazione, tra cui la creazione di oggetti personalizzati che possono essere aggiunti all'API Oracle Sales Automation RESTful.
Suggerimenti sulle prestazioni
Per ottenere le migliori prestazioni dalle API REST di Oracle Fusion Sales Cloud, segui questi suggerimenti.
- Eseguire una query solo sui dati necessari.
- Eseguire una query solo sui dati, non sui metadati.
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=trueCerca risorse RESTful utilizzando gli endpoint "Descrivi"
È possibile ottenere dettagli specifici sulle diverse API Oracle Sales Automation RESTful inviando una richiesta HTTP GET che restituisce un oggetto JSON contenente informazioni sulle risorse e metadati complementari.
Ottenere gli endpoint dei servizi per i servizi Web RESTful
È possibile derivare il nome di un endpoint del servizio Web Oracle Sales Automation RESTful specificando il nome del servizio anziché la parola chiave "describe" nell'URL dell'API.
Informazioni sulle operazioni REST e sulle strutture dei payload
Il servizio Web RESTful per ogni oggetto standard di Oracle Sales Automation fornisce diverse operazioni di creazione, lettura, aggiornamento ed eliminazione (CRUD).
È possibile eseguire i seguenti metodi standard per interagire con una singola risorsa o con una raccolta di risorse tramite i relativi URL:
| Metodo | Disponibile per una risorsa singolare | Disponibile per una raccolta risorse |
|---|---|---|
| Recupera | Y | N |
| Invia | N | Y |
| Patch | Y | N |
| Eliminazione | Y | N |
Informazioni sul metodo Get
Utilizzare questo metodo per eseguire query e recuperare informazioni. Tuttavia, i parametri utilizzati nella query per perfezionare la ricerca o limitare i risultati in una singola risorsa sono diversi da quelli utilizzati in una raccolta di risorse.
Parametri per le risorse singolari e di raccolta
Nel metodo di interrogazione di una singola risorsa e di una risorsa di raccolta vengono utilizzati i parametri riportati di seguito.
| Parametro | Formato | Descrizione |
|---|---|---|
expand |
o
|
Restituisce la risorsa padre, inclusi i relativi figli. Per impostazione predefinita non restituisce alcun figlio. |
fields |
fields=<FieldName1>,<FieldName2>... |
Selezionare solo i campi le cui informazioni sono obbligatorie. |
onlyData |
o
|
Recupera solo i dati e non gli URL delle risorse. Per impostazione predefinita vengono restituiti tutti gli URL figlio risorsa. |
Parametri per le risorse di raccolta
Un metodo GET per la risorsa di raccolta utilizza i parametri sopra descritti e i seguenti parametri:
| Parametro | Formato | Descrizione |
|---|---|---|
limit |
|
Numero intero maggiore di 0 che specifica il numero massimo di elementi restituiti dal server. Se non viene specificato alcun valore limite, il server utilizzerà un valore limite predefinito. |
offset |
offset=<Integer> |
Valore intero che specifica l'indice del primo elemento da restituire. L'indice di offset inizia con 0. |
q |
|
Specificare una condizione di filtro per limitare gli articoli restituiti nella raccolta. Il valore di questo parametro di query contiene una o più espressioni separate da ";". Ad esempio Operatori supportati:
Caratteri speciali:
|
totalResults |
o
|
Valore booleano che specifica se restituire il numero totale di elementi che corrispondono al parametro di query "q".
|
orderBy |
|
Specifica l'ordine degli articoli restituiti nel payload della risposta. Il valore del parametro di query è una stringa separata da virgole di nomi di campo, ciascuno seguito facoltativamente da due punti e dalla parola chiave Se non specificato, il server restituisce gli elementi in ordine crescente. |
finder |
|
Utilizza una "query" predefinita che ha i propri parametri speciali. Ad esempio, la risorsa |
dependency |
|
Utilizzato per le risorse elenco di valori a catena. Ad esempio, se una risorsa Location dispone di un campo State, tali valori verranno derivati da un'altra risorsa States che restituisce una lista di stati per un paese (posizione) specifico. Se ad esempio Location è: US e State è CA. La risorsa Stati contiene un elenco di tutti gli Stati Uniti, ma se l'utente nella pagina web cambia le impostazioni nazionali in Brasile, il modo per recuperare tutti gli stati brasiliani sarebbe con una chiamata come questa:
|
Informazioni sul metodo Post
Utilizzare questo metodo per creare un nuovo elemento. L'intestazione del tipo di supporto della richiesta è:
application/vnd.oracle.adf.resourceitem+jsonAd esempio, per creare una nuova opportunità nella risorsa Opportunities, la richiesta passa il nuovo parametro del nome Opportunità in un oggetto JSON:
{
"Name" : "New Opportunity Name"
}Il corpo della risposta dell'oggetto JSON restituito dalla richiesta POST sarebbe simile al seguente:
{
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"
…
}Informazioni sul metodo di patch
Utilizzare questo metodo per effettuare aggiornamenti parziali a una risorsa. Verranno aggiornati solo i campi contenuti nel corpo della richiesta.
Il tipo di supporto della richiesta è:
application/vnd.oracle.adf.resourceitem+jsonAd esempio, per aggiornare un'opportunità esistente dalla risorsa Oppurtunities, la richiesta HTTP PATCH passa come corpo della richiesta il seguente oggetto JSON:
{
"Name": "Opportunity Name Updated"
}La risposta di questa richiesta è un oggetto JSON simile al seguente:
{
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"
…
}Informazioni sul metodo di eliminazione
Utilizzare questo metodo per eliminare una risorsa. Non richiede un corpo della richiesta.
Ad esempio, per eliminare un oggetto Opportunità dalla risorsa Opportunities, è necessario effettuare la richiesta DELETE direttamente all'URI della risorsa Opportunity figlio da eliminare, senza passare alcun parametro:
https://<crm_server:PortNumber>/salesApi/resources/latest/opportunities/<OpportunityNumber>
Informazioni sui metodi di azione personalizzati
A volte, una risorsa espone un'azione personalizzata che non rientra nello standard CRUD. Un'azione personalizzata viene sempre richiamata con POST (sia per le raccolte singole che per quelle di risorse) e il relativo tipo di supporto di richiesta è:
application/vnd.oracle.adf.action+jsonIl tipo di supporto di risposta è:
application/vnd.oracle.adf.actionresult+jsonAd esempio, in Oracle Sales Automation la risorsa leads in https://<crm_server:portNumber>/salesApi/resources/latest/describe/leads/ dispone di un'azione personalizzata per convertire un lead in opportunità denominata 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" ]
},Pensa a un'azione personalizzata come a una serie di passi, a un processo o a una combinazione di diverse operazioni CRUD per raggiungere un obiettivo specifico. Nell'esempio riportato sopra, il corpo della richiesta di un'azione personalizzata deve passare il "nome" che sarà il nome dell'azione personalizzata (ad esempio convertLeadToOpty) e facoltativamente un array di parametri di input per l'azione personalizzata (ad esempio leadId).
Di solito il corpo JSON della richiesta POST contiene:
{
"$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"
]
}L'oggetto risposta JSON contiene il risultato del metodo azione personalizzata nel campo "risultati".
Informazioni sul supporto batch
Per migliorare le prestazioni, è possibile combinare più operazioni in una singola richiesta HTTP inviando un oggetto JSON contenente un campo denominato "parti" come array di oggetti. Ogni oggetto all'interno dell'array contiene un ID univoco, un percorso relativo alla risorsa, un'operazione e, facoltativamente, un payload.
Lo schema JSON della richiesta HTTP è:
{
"$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"
]
}
Ad esempio, la richiesta seguente recupererà un dipendente esistente e aggiornerà un altro dipendente:
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
}
}
]
}
La risposta della richiesta precedente utilizza lo stesso tipo di supporto della richiesta e restituisce un oggetto JSON come il seguente:
{"parts":[
{
"id":"part1",
"path":"/latest/hremployees/101",
"operation":"get",
"payload" : {
"EmployeeId" : 101
…
},
{
"id" : "part2",
"path" : "/latest/hremployees/102",
"operation" : "update",
"payload" : {
"EmployeeId" : 102,
} ]}Test di una richiesta di servizio Web Oracle Sales Automation RESTful
Per eseguire il test di un'interfaccia API RESTful e ottenere i dati richiesti, è possibile utilizzare lo strumento della riga di comando cURL per trasferire dati da o verso un server utilizzando uno dei protocolli supportati, ad esempio HTTP o HTTPS.