Mit RESTful Services auf Oracle Sales Automation-Daten zugreifen
Jede API enthält Oracle Sales Automation-Standardobjekte und jedes Objekt ist einer REST-Ressource oder Ressourcensammlung zugeordnet. Beispiel: In der RESTful-API wird der Ressourcenendpunkt Opportunities verwendet, um Informationen zu einem potenziellen Verkauf zu verfolgen. Bevor Sie jedoch Oracle Sales Automation RESTful-Webservices verwenden, müssen Sie die Sicherheitsanforderungen für den Zugriff berücksichtigen und auch die zu verwendenden Webservices sowie die entsprechenden unterstützten Methoden und erwarteten Payload-Strukturen identifizieren.
Informationen zu Ressourcen in Oracle Sales Automation RESTful-APIs
Oracle Sales Automation stellt eine Sammlung von REST-Ressourcen für Standard- und benutzerdefinierte Objekte bereit.
Ein wichtiges Konzept in jeder RESTful-API ist die Ressource. Eine Ressource ist ein Objekt mit einem Typ (z.B. Opportunitys), zugehörigen Daten, Beziehungen zu anderen Ressourcen und einer Gruppe von Methoden, die daran arbeiten. Diese Ressourcen sind hierarchisch organisiert und umfassen:
-
Root-Ressource: Entspricht einem logischen Objekt, wie einer Opportunity oder einem Lead.
-
Unterressource(n): Dies sind Ressourcen, die zu einer übergeordneten Ressource gehören, z.B. ein Kontakt für eine Opportunity.
-
Wertelistenressource: Eine Liste gültiger Werte, die beim Festlegen eines Wertes für ein Feld verwendet werden können. Es gibt zwei Typen: Lookup (statische Liste) oder Dynamisch (basierend auf Kontext).
Innerhalb der Oracle Sales Automation-API RESTful gibt es zwei Ressourcentypen: eine einzelne Ressource oder eine Erfassungsressource. Eine einzelne Ressource kann eine einzelne Entität wie ein Mitarbeiter oder eine Bestellung darstellen, während eine Inkassoressource umfassender sein kann, wie eine Liste von Mitarbeitern oder eine Liste von Bestellungen, die ausgelagert werden können.
REST-Unterstützung für benutzerdefinierte Objekte
Oracle Sales Automation umfasst Standardobjekte, die viele Geschäftsanforderungen und Szenarios berücksichtigen. Zusätzlich zu Standardobjekten können Sie jedoch das Application Composer-Tool verwenden, um benutzerdefinierte Objekte der obersten Ebene und untergeordnete benutzerdefinierte Objekte zu erstellen, wenn Sie eine eindeutige Geschäftsanforderung haben.
Application Composer ist ein browserbasiertes Tool, mit dem Business Analysts und Administratoren (nicht nur Entwickler) Oracle Sales Automation anpassen können. Mit diesem Tool können Sie die Arten von Datenmodelländerungen vornehmen, die in der Vergangenheit nur von Entwicklern vorgenommen wurden. Im Application Composer-Tool können Sie Änderungen direkt vornehmen und sofort zur Verwendung verfügbar machen, ohne sich wieder bei der Anwendung anmelden zu müssen. Dazu gehört die Erstellung von benutzerdefinierten Objekten, die der Oracle Sales Automation-API RESTful hinzugefügt werden können.
Performancetipps
Befolgen Sie diese Tipps, um die beste Performance mit den REST-APIs von Oracle Fusion Sales Cloud zu erzielen.
- Fragen Sie nur die Daten ab, die Sie benötigen.
- Fragen Sie nur die Daten ab, nicht die Metadaten.
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=trueMit "Beschreiben"-Endpunkten nach RESTful-Ressourcen suchen
Sie können bestimmte Details zu den verschiedenen Oracle Sales Automation-APIs RESTful abrufen, indem Sie eine HTTP GET-Anforderung senden, die ein JSON-Objekt mit Ressourceninformationen und ergänzenden Metadaten zurückgibt.
Serviceendpunkte für RESTful-Webservices abrufen
Sie können den Namen eines Oracle Sales Automation RESTful-Webserviceendpunkts inferenzieren, indem Sie den Servicenamen anstelle des Schlüsselworts "beschreiben" in der API-URL angeben.
REST-Vorgänge und Payload-Strukturen
Der Webservice RESTful für jedes Oracle Sales Automation-Standardobjekt bietet mehrere CRUD-(Create, Read, Update and Delete-)Vorgänge.
Sie können die folgenden Standardmethoden für die Interaktion mit einer einzelnen Ressource oder einer Ressourcensammlung über ihre URLs ausführen:
| Methode | Für eine einzelne Ressource verfügbar | Für eine Ressourcenerfassung verfügbar |
|---|---|---|
| Get | J | N |
| Post | N | J |
| Patch | J | N |
| Löschen | J | N |
Informationen zur Get-Methode
Verwenden Sie diese Methode, um Informationen abzufragen und abzurufen. Die Parameter, die in der Abfrage verwendet werden, um die Suche zu verfeinern oder die Ergebnisse in einer einzelnen Ressource einzugrenzen, unterscheiden sich jedoch von den Parametern, die in einer Ressourcensammlung verwendet werden.
Parameter für Singular- und Collection-Ressourcen
Die folgenden Parameter werden bei der Methode zum Abfragen einer einzelnen Ressource sowie einer Collection-Ressource verwendet:
| Parameter | Formatieren | Beschreibung |
|---|---|---|
expand |
oder
|
Gibt die übergeordnete Ressource einschließlich ihrer untergeordneten Ressourcen zurück. Standardmäßig werden keine untergeordneten Elemente zurückgegeben. |
fields |
fields=<FieldName1>,<FieldName2>... |
Wählen Sie nur bestimmte Felder, für die Informationen erforderlich sind. |
onlyData |
oder
|
Rufen Sie nur Daten und keine Ressourcen-URLs ab. Standardmäßig werden alle untergeordneten Ressourcen-URLs zurückgegeben. |
Parameter für Inkassoressourcen
Eine GET-Methode für Erfassungsressourcen verwendet die oben beschriebenen Parameter sowie die folgenden Parameter:
| Parameter | Formatieren | Beschreibung |
|---|---|---|
limit |
|
Eine Ganzzahl größer als 0, die angibt, wie viele Elemente maximal vom Server zurückgegeben werden. Wenn kein Grenzwert angegeben wird, verwendet der Server einen Standardgrenzwert. |
offset |
offset=<Integer> |
Ein ganzzahliger Wert, der den Index des ersten zurückzugebenden Elements angibt. Der Offset-Index beginnt bei 0. |
q |
|
Geben Sie eine Filterbedingung an, um die in der Sammlung zurückgegebenen Elemente einzuschränken. Der Wert dieses Abfrageparameters enthält einen oder mehrere durch ";" getrennte Ausdrücke. Beispiel: Unterstützte Operatoren:
Sonderzeichen:
|
totalResults |
oder
|
Ein boolescher Wert, der angibt, ob die Gesamtanzahl der Elemente zurückgegeben wird, die dem Abfrageparameter "q" entsprechen.
|
orderBy |
|
Gibt die Reihenfolge der in der Antwort-Payload zurückgegebenen Elemente an. Der Abfrageparameterwert ist eine durch Komma getrennte Zeichenfolge von Feldnamen, jeder optional gefolgt von einem Doppelpunkt und dem Schlüsselwort Wenn keine Angabe gemacht wird, gibt der Server Elemente in aufsteigender Reihenfolge zurück. |
finder |
|
Verwendet eine vordefinierte Abfrage mit eigenen speziellen Parametern. Beispiel: Die Ressource |
dependency |
|
Wird für kaskadierende Wertelistenressourcen verwendet. Beispiel: Wenn eine Location-Ressource ein Feld State enthält, werden diese Werte von einer anderen States-Ressource abgeleitet, die eine Liste der Status für ein bestimmtes Land (Standort) zurückgibt. Beispiel: Standort: US und Bundesland: CA. Die Ressource "Bundesstaaten" enthält eine Liste aller US-Bundesstaaten. Wenn der Benutzer auf der Webseite das Gebietsschema jedoch in "Brasilien" ändert, können alle brasilianischen Bundesstaaten wie folgt abgerufen werden:
|
Über die Post-Methode
Mit dieser Methode können Sie ein neues Element erstellen. Der Header des Anforderungsmedientyps lautet:
application/vnd.oracle.adf.resourceitem+jsonBeispiel: Um eine neue Opportunity unter der Ressource Opportunities zu erstellen, übergibt die Anforderung den neuen Namensparameter Opportunity in einem JSON-Objekt:
{
"Name" : "New Opportunity Name"
}Der Antwortbody des JSON-Objekts, das von der POST-Anforderung zurückgegeben wird, könnte wie folgt aussehen:
{
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"
…
}Informationen zur Patchmethode
Mit dieser Methode können Sie eine Ressource teilweise aktualisieren. Nur die Felder im Anforderungstext werden aktualisiert.
Der Anforderungstyp lautet:
application/vnd.oracle.adf.resourceitem+jsonBeispiel: Um ein vorhandenes Opportunity aus der Ressource Oppurtunities zu aktualisieren, übergibt die HTTP-PATCH-Anforderung das folgende JSON-Objekt als Anforderungstext:
{
"Name": "Opportunity Name Updated"
}Die Antwort dieser Anforderung ist ein JSON-Objekt ähnlich dem Folgenden:
{
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"
…
}Informationen zur Methode "Delete"
Mit dieser Methode können Sie eine Ressource löschen. Es ist kein Anforderungsbody erforderlich.
Beispiel: Um ein Verkaufsprojekt-Objekt aus der Ressource Opportunities zu löschen, muss die Anforderung DELETE direkt an die URI der zu löschenden untergeordneten Ressource Opportunity gesendet werden, ohne dass Parameter an sie übergeben werden:
https://<crm_server:PortNumber>/salesApi/resources/latest/opportunities/<OpportunityNumber>
Informationen zu benutzerdefinierten Aktionsmethoden
Manchmal zeigt eine Ressource eine benutzerdefinierte Aktion an, die nicht in den CRUD-Standard passt. Eine benutzerdefinierte Aktion wird immer mit POST (sowohl für Singular- als auch für Ressourcensammlungen) aufgerufen. Der Anforderungsmedientyp lautet:
application/vnd.oracle.adf.action+jsonDer Antwortmedientyp lautet:
application/vnd.oracle.adf.actionresult+jsonBeispiel: In Oracle Sales Automation enthält die Ressource leads unter https://<crm_server:portNumber>/salesApi/resources/latest/describe/leads/ eine benutzerdefinierte Aktion zum Konvertieren eines Leads in eine Opportunity namens 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" ]
},Stellen Sie sich eine benutzerdefinierte Aktion als eine Reihe von Schritten, einen Prozess oder eine Kombination verschiedener CRUD-Vorgänge vor, um ein bestimmtes Ziel zu erreichen. Im obigen Beispiel muss der Anforderungsbody einer benutzerdefinierten Aktion den "Namen" übergeben, der diesen benutzerdefinierten Aktionsnamen (d.h. convertLeadToOpty) und optional ein Array von Eingabeparametern für die benutzerdefinierte Aktion (d.h. leadId) sein soll.
Normalerweise enthält der JSON-Hauptteil der POST-Anforderung Folgendes:
{
"$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"
]
}Das JSON-Antwortobjekt enthält das Ergebnis der Methode benutzerdefinierte Aktion im Feld "Ergebnisse".
Informationen zur Batchunterstützung
Um die Performance zu verbessern, können mehrere Vorgänge zu einer einzelnen HTTP-Anforderung kombiniert werden, indem ein JSON-Objekt gesendet wird, das ein Feld mit dem Namen "parts" als Array von Objekten enthält. Jedes Objekt innerhalb des Arrays enthält eine eindeutige ID, einen relativen Pfad zur Ressource, einen Vorgang und optional eine Payload.
Das JSON-Schema der HTTP-Anforderung lautet:
{
"$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"
]
}
Beispiel: Die folgende Anforderung ruft einen vorhandenen Mitarbeiter ab und aktualisiert einen anderen Mitarbeiter:
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
}
}
]
}
Die Antwort der vorherigen Anforderung verwendet denselben Medientyp wie die Anforderung und gibt ein JSON-Objekt zurück. Beispiel:
{"parts":[
{
"id":"part1",
"path":"/latest/hremployees/101",
"operation":"get",
"payload" : {
"EmployeeId" : 101
…
},
{
"id" : "part2",
"path" : "/latest/hremployees/102",
"operation" : "update",
"payload" : {
"EmployeeId" : 102,
} ]}Oracle Sales Automation RESTful-Webserviceanfrage testen
Um eine RESTful-API zu testen und die erforderlichen Daten abzurufen, können Sie mit dem cURL-Befehlszeilentool Daten von oder zu einem Server mit einem der unterstützten Protokolle wie HTTP oder HTTPS übertragen.