Accéder aux données d'Oracle Sales Automation à l'aide des services RESTful
Chaque API contient des objets Oracle Sales Automation standard et chaque objet est associé à une ressource REST ou à une collecte de ressources. Par exemple, dans l'API RESTful, l'adresse de ressource Opportunities est utilisée pour suivre les informations relatives à une vente potentielle. Toutefois, avant d'utiliser les services Web Oracle Sales Automation RESTful, vous devez prendre en compte les exigences de sécurité pour obtenir l'accès et identifier les services Web à utiliser, ainsi que les méthodes prises en charge correspondantes et les structures de charge utile attendues.
A propos des ressources dans les API Oracle Sales Automation RESTful
Oracle Sales Automation fournit un ensemble de ressources REST pour les objets standard et personnalisés.
La ressource est un concept important dans toute API RESTful. Une ressource est un objet avec un type (par exemple, Opportunités), des données associées, des relations avec d'autres ressources et un ensemble de méthodes qui l'utilisent. Ces ressources sont organisées de manière hiérarchique et comprennent :
-
Ressource racine : Correspond à un objet logique, tel qu'une opportunité ou une piste.
-
Sous-ressources : il s'agit de ressources appartenant à une ressource parent, par exemple un contact pour une opportunité.
-
Ressource Liste de valeurs : liste des valeurs valides pouvant être utilisées lors de la définition d'une valeur pour un champ. Il existe deux types : Recherche (liste statique) ou Dynamique (basé sur le contexte).
Dans l'API RESTful d'Oracle Sales Automation, il existe deux types de ressource : une ressource unique ou une ressource de collecte. Une ressource unique peut représenter une entité unique, telle qu'un employé ou une commande d'achat, tandis qu'une ressource de collecte peut être plus complète, telle qu'une liste d'employés ou une liste de commandes d'achat pouvant être paginées.
A propos de la prise en charge REST des objets personnalisés
Oracle Sales Automation inclut des objets standard qui tiennent compte de nombreux besoins et scénarios commerciaux. Toutefois, en plus des objets standard, vous pouvez utiliser l'outil Application Composer pour créer à la fois des objets personnalisés de niveau supérieur et des objets personnalisés enfant si vous avez un besoin métier unique.
Application Composer est un outil basé sur un navigateur que les analystes métier et les administrateurs (et pas seulement les développeurs) peuvent utiliser pour personnaliser Oracle Sales Automation. A l'aide de cet outil, vous pouvez effectuer les types de modification de modèle de données qui, dans le passé, n'ont été effectués que par les développeurs. Dans l'outil Application Composer, vous pouvez apporter des modifications à la volée et les utiliser immédiatement sans avoir à vous reconnecter à l'application. Cela inclut la création d'objets personnalisés qui peuvent être ajoutés à l'API RESTful Oracle Sales Automation.
Conseils de performances
Pour obtenir les meilleures performances des API REST Oracle Fusion Sales Cloud, suivez ces conseils.
- Interrogez uniquement les données dont vous avez besoin.
- Interrogez uniquement les données, pas les métadonnées.
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=trueRechercher des ressources RESTful à l'aide d'adresses de description
Vous pouvez obtenir des détails spécifiques sur les différentes API RESTful d'Oracle Sales Automation en envoyant une demande HTTP GET qui renvoie un objet JSON contenant des informations sur les ressources et des métadonnées complémentaires.
Obtention des adresses de service pour les services Web RESTful
Vous pouvez inférer le nom d'une adresse de service Web RESTful Oracle Sales Automation en indiquant le nom du service au lieu du mot-clé "describe" dans l'URL d'API.
A propos des opérations REST et des structures de charge utile
Le service Web RESTful pour chaque objet Oracle Sales Automation standard fournit plusieurs opérations de création, de lecture, de mise à jour et de suppression (CRUD).
Vous pouvez exécuter les méthodes standard suivantes pour interagir avec une ressource singulière ou un ensemble de ressources via leurs URL :
| Méthode | Disponible pour une ressource unique | Disponible pour un ensemble de ressources |
|---|---|---|
| GET | O | N |
| POST | N | O |
| Appliquer un patch | O | N |
| Suppression | O | N |
A propos de la méthode Get
Utilisez cette méthode pour interroger et extraire des informations. Toutefois, les paramètres utilisés dans la requête pour affiner la recherche ou affiner les résultats dans une ressource singulière sont différents de ceux utilisés dans un ensemble de ressources.
Paramètres pour les ressources singulières et de collecte
Les paramètres suivants sont utilisés dans la méthode d'interrogation d'une ressource singulière et d'une ressource de collection :
| Paramètre | Format | Description |
|---|---|---|
expand |
ou
|
Renvoie la ressource parent, y compris ses enfants. Par défaut, il ne renvoie aucun enfant. |
fields |
fields=<FieldName1>,<FieldName2>... |
Sélectionnez uniquement certains champs dont les informations sont obligatoires. |
onlyData |
ou
|
Extrayez uniquement les données et non les URL de ressource. Par défaut, toutes les URL enfant des ressources sont renvoyées. |
Paramètres pour les ressources de collecte
Une méthode GET pour une ressource de collecte utilise les paramètres décrits ci-dessus ainsi que les paramètres suivants :
| Paramètre | Format | Description |
|---|---|---|
limit |
|
Nombre entier supérieur à 0 qui indique le nombre maximal d'éléments renvoyés par le serveur. Si aucune valeur limite n'est spécifiée, le serveur utilise une valeur limite par défaut. |
offset |
offset=<Integer> |
Valeur entière indiquant l'index du premier élément à renvoyer. L'index de décalage commence à 0. |
q |
|
Spécifiez une condition de filtre pour restreindre les éléments renvoyés dans la collection. La valeur de ce paramètre de requête contient une ou plusieurs expressions séparées par " ;". Par exemple, Opérateurs pris en charge:
Caractères spéciaux:
|
totalResults |
ou
|
Valeur booléenne indiquant si le nombre total d'éléments correspondant au paramètre de requête "q" doit être renvoyé.
|
orderBy |
|
Indique l'ordre des éléments renvoyés dans la charge utile de réponse. La valeur du paramètre de requête est une chaîne de noms de champ séparés par des virgules, chacun éventuellement suivi d'un signe deux-points et du mot-clé S'il n'est pas spécifié, le serveur renvoie les éléments dans l'ordre croissant. |
finder |
|
Utilise une "requête" prédéfinie qui a ses propres paramètres spéciaux. Par exemple, la ressource |
dependency |
|
Utilisé pour les ressources de liste de valeurs en cascade. Par exemple, si une ressource Location comporte un champ State, ces valeurs seront dérivées d'une autre ressource States qui renvoie la liste des états pour un pays (emplacement) spécifique. Si, par exemple, Location est : US et State est CA. La ressource États contient une liste de tous les États américains, mais si l'utilisateur sur la page Web change l'environnement local en Brésil, la façon de récupérer tous les États brésiliens serait avec un appel comme celui-ci :
|
A propos de la méthode Post
Utilisez cette méthode pour créer un élément. L'en-tête du type de support de demande est :
application/vnd.oracle.adf.resourceitem+jsonPar exemple, pour créer une opportunité sous la ressource Opportunities, la demande transmet le nouveau paramètre de nom d'opportunité dans un objet JSON :
{
"Name" : "New Opportunity Name"
}Le corps de réponse de l'objet JSON renvoyé par la demande POST serait le suivant :
{
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"
…
}A propos de la méthode d'application de patches
Utilisez cette méthode pour effectuer des mises à jour partielles d'une ressource. Seuls les champs contenus dans le corps de la demande seront mis à jour.
Le type de support de demande est :
application/vnd.oracle.adf.resourceitem+jsonPar exemple, pour mettre à jour une opportunité existante à partir de la ressource Oppurtunities, la demande HTTP PATCH transmet l'objet JSON suivant en tant que corps de demande :
{
"Name": "Opportunity Name Updated"
}La réponse de cette demande est un objet JSON similaire à ce qui suit :
{
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"
…
}A propos de la méthode Delete
Utilisez cette méthode pour supprimer une ressource. Il ne nécessite pas de corps de demande.
Par exemple, pour supprimer un objet Opportunity de la ressource Opportunities, la demande DELETE doit être effectuée directement vers l'URI de la ressource Opportunity enfant à supprimer, sans lui transmettre aucun paramètre :
https://<crm_server:PortNumber>/salesApi/resources/latest/opportunities/<OpportunityNumber>
A propos des méthodes d'action personnalisées
Parfois, une ressource expose une action personnalisée qui ne correspond pas à la norme CRUD. Une action personnalisée est toujours appelée avec POST (pour les collections singulières et de ressources) et son type de média de demande est :
application/vnd.oracle.adf.action+jsonLe type de support de réponse est :
application/vnd.oracle.adf.actionresult+jsonPar exemple, dans Oracle Sales Automation, la ressource leads sous https://<crm_server:portNumber>/salesApi/resources/latest/describe/leads/ dispose d'une action personnalisée pour convertir une piste en opportunité appelée : 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" ]
},Considérez une action personnalisée comme une série d'étapes, un processus ou une combinaison de différentes opérations CRUD pour atteindre un objectif spécifique. Dans l'exemple ci-dessus, le corps de demande d'une action personnalisée doit transmettre le "nom" qui sera ce nom d'action personnalisée (par exemple, convertLeadToOpty) et éventuellement un tableau de paramètres d'entrée pour l'action personnalisée (par exemple, leadId).
En général, le corps JSON de la demande POST contient :
{
"$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'objet de réponse JSON contient le résultat de la méthode d'action personnalisée dans le champ "résultats".
A propos de la prise en charge par lots
Pour améliorer les performances, plusieurs opérations peuvent être combinées en une seule demande HTTP en envoyant un objet JSON contenant un champ nommé "parts" sous forme de tableau d'objets. Chaque objet du tableau contient un ID unique, un chemin relatif vers la ressource, une opération et éventuellement une charge utile.
Le schéma JSON de la demande HTTP est le suivant :
{
"$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"
]
}
Par exemple, la demande suivante permet d'extraire un employé existant et de mettre à jour un autre employé :
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 réponse de la demande précédente utilise le même type de média que la demande et renvoie un objet JSON tel que :
{"parts":[
{
"id":"part1",
"path":"/latest/hremployees/101",
"operation":"get",
"payload" : {
"EmployeeId" : 101
…
},
{
"id" : "part2",
"path" : "/latest/hremployees/102",
"operation" : "update",
"payload" : {
"EmployeeId" : 102,
} ]}Test d'une demande de service Web Oracle Sales Automation RESTful
Pour tester une API RESTful et obtenir les données requises, vous pouvez utiliser l'outil de ligne de commande cURL pour transférer des données depuis ou vers un serveur à l'aide de l'un des protocoles pris en charge, tels que HTTP ou HTTPS.