Acceso a los datos de Oracle Sales Automation mediante los servicios RESTful
Cada API contiene objetos estándar de Oracle Sales Automation y cada objeto está asociado a un recurso o una recopilación de recursos de REST. Por ejemplo, en la API RESTful, el punto final del recurso Opportunities se utiliza para realizar un seguimiento de la información sobre una venta potencial. Sin embargo, antes de utilizar los servicios web RESTful de Oracle Sales Automation, debe tener en cuenta los requisitos de seguridad para obtener acceso y también identificar qué servicios web utilizar, junto con sus métodos soportados correspondientes y las estructuras de carga útil esperadas.
Acerca de los recursos de las API de Oracle Sales Automation RESTful
Oracle Sales Automation proporciona una recopilación de recursos REST para objetos estándar y personalizados.
Un concepto importante en cualquier API de RESTful es el recurso. Un recurso es un objeto con un tipo (por ejemplo, Oportunidades), datos asociados, relaciones con otros recursos y un conjunto de métodos que operan en él. Estos recursos se organizan de forma jerárquica e incluyen:
-
Recurso raíz: corresponde a un objeto lógico, como una oportunidad u oportunidad potencial.
-
Subrecursos: son recursos que pertenecen a un recurso principal; por ejemplo, un contacto para una oportunidad.
-
Recurso de lista de valores: lista de valores válidos que se pueden utilizar al definir un valor para un campo. Hay dos tipos: Búsqueda (lista estática) o Dinámica (basada en el contexto).
En la API RESTful de Oracle Sales Automation, hay dos tipos de recursos: un único recurso o un recurso de recopilación. Un único recurso puede representar una sola entidad, como un empleado o una orden de compra, mientras que un recurso de cobro puede ser más completo, como una lista de empleados o una lista de órdenes de compra que se pueden paginar.
Acerca del soporte de REST para objetos personalizados
Oracle Sales Automation incluye objetos estándar que responden a muchas necesidades y escenarios empresariales. Sin embargo, además de los objetos estándar, puede utilizar la herramienta Application Composer para crear objetos personalizados de nivel superior y objetos personalizados secundarios si tiene una necesidad de negocio única.
Application Composer es una herramienta basada en explorador que los analistas y administradores de negocio (no solo los desarrolladores) pueden utilizar para personalizar Oracle Sales Automation. Al utilizar esta herramienta, puede realizar los tipos de cambios del modelo de datos que en el pasado solo habían realizado los desarrolladores. En la herramienta Application Composer puede realizar cambios sobre la marcha y estarán disponibles inmediatamente para su uso sin tener que volver a conectarse a la aplicación. Esto incluye la creación de objetos personalizados que se pueden agregar a la API RESTful de Oracle Sales Automation.
Consejos de Rendimiento
Para obtener el mejor rendimiento de las API de REST de Oracle Fusion Sales Cloud, siga estos consejos.
- Consulta solo los datos que necesitas.
- Consulta sólo los datos, no los metadatos.
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=trueBuscar recursos RESTful mediante puntos finales "Describir"
Puede obtener detalles específicos sobre las diferentes API RESTful de Oracle Sales Automation enviando una solicitud HTTP GET que devuelva un objeto JSON que contenga información de recursos y metadatos complementarios.
Obtener los puntos finales del servicio para los servicios web RESTful
Puede inferir el nombre de un punto final de servicio web de Oracle Sales Automation RESTful especificando el nombre del servicio en lugar de la palabra clave "describir" en la URL de API.
Acerca de las estructuras de carga útil y operaciones REST
El servicio web RESTful para cada objeto estándar de Oracle Sales Automation proporciona varias operaciones de creación, lectura, actualización y supresión (CRUD).
Puede ejecutar los siguientes métodos estándar para interactuar con un recurso singular o una recopilación de recursos a través de sus URL:
| Método | Disponible para un recurso singular | Disponible para una recopilación de recursos |
|---|---|---|
| Get | S | N |
| Post | N | S |
| Aplicar parches | S | N |
| Suprimir | S | N |
Acerca del Método Get
Utilice este método para consultar y recuperar información. Sin embargo, los parámetros utilizados en la consulta para acotar la búsqueda o acotar los resultados en un recurso singular son diferentes de los utilizados en una recopilación de recursos.
Parámetros para Recursos Singulares y de Recopilación
Los siguientes parámetros se utilizan en el método para consultar un recurso singular y un recurso de recopilación:
| parámetro | Formato | Descripción |
|---|---|---|
expand |
o bien,
|
Devuelve el recurso principal, incluidos sus secundarios. Por defecto, no devuelve ningún secundario. |
fields |
fields=<FieldName1>,<FieldName2>... |
Seleccione solo determinados campos cuya información sea necesaria. |
onlyData |
o bien,
|
Recupere solo datos y no ninguna URL de recurso. Por defecto, se devuelven todas las URL secundarias de recursos. |
Parámetros para recursos de cobro
Un método GET para el recurso de recopilación utiliza los parámetros descritos anteriormente, así como los siguientes parámetros:
| parámetro | Formato | Descripción |
|---|---|---|
limit |
|
Un entero mayor que 0 que especifica el número máximo de elementos devueltos por el servidor. Si no se especifica un valor de límite, el servidor usará un valor de límite por defecto. |
offset |
offset=<Integer> |
Valor entero que especifica el índice del primer elemento que se va a devolver. El índice de desplazamiento comienza en 0. |
q |
|
Especifique una condición de filtro para restringir los elementos devueltos en la recopilación. El valor de este parámetro de consulta contiene una o más expresiones separadas por ";". Por ejemplo, Operadores soportados:
Caracteres especiales:
|
totalResults |
o bien,
|
Valor booleano que especifica si se debe devolver el número total de elementos que coinciden con el parámetro de consulta "q".
|
orderBy |
|
Especifica el orden de los elementos devueltos en la carga útil de respuesta. El valor del parámetro de consulta es una cadena separada por comas de nombres de campo, cada uno opcionalmente seguido de dos puntos y la palabra clave Si no se especifica, el servidor devuelve los elementos en orden ascendente. |
finder |
|
Utiliza una "consulta" predefinida que tiene sus propios parámetros especiales. Por ejemplo, el recurso |
dependency |
|
Se utiliza para los recursos de lista de valores en cascada. Por ejemplo, si un recurso Location tiene un campo State, esos valores se derivarán de otro recurso States que devuelva una lista de estados para un país (ubicación) específico. Si, por ejemplo, Location es: US y State es CA. El recurso de estados contiene una lista de todos los estados de EE. UU., pero si el usuario en la página web cambia la configuración regional a Brasil, la forma de recuperar todos los estados de Brasil sería con una llamada como esta:
|
Acerca del método de publicación
Utilice este método para crear un nuevo elemento. La cabecera del tipo de medio de solicitud es:
application/vnd.oracle.adf.resourceitem+jsonPor ejemplo, para crear una nueva oportunidad en el recurso Opportunities, la solicitud transfiere el nuevo parámetro de nombre de Oportunidad en un objeto JSON:
{
"Name" : "New Opportunity Name"
}El cuerpo de respuesta del objeto JSON devuelto por la solicitud POST sería algo así:
{
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"
…
}Acerca del Método de Parches
Utilice este método para realizar actualizaciones parciales en un recurso. Solo se actualizarán los campos incluidos en el cuerpo de la solicitud.
El tipo de medio de solicitud es:
application/vnd.oracle.adf.resourceitem+jsonPor ejemplo, para actualizar una oportunidad existente del recurso Oppurtunities, la solicitud HTTP PATCH transfiere el siguiente objeto JSON como cuerpo de la solicitud:
{
"Name": "Opportunity Name Updated"
}La respuesta de esta solicitud es un objeto JSON similar a este:
{
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"
…
}Acerca del Método de Supresión
Utilice este método para suprimir un recurso. No requiere un cuerpo de solicitud.
Por ejemplo, para suprimir un objeto Opportunity del recurso Opportunities, la solicitud DELETE se debe realizar directamente en el URI del recurso Opportunity secundario para suprimirlo, sin transferirle ningún parámetro:
https://<crm_server:PortNumber>/salesApi/resources/latest/opportunities/<OpportunityNumber>
Acerca de los métodos de acción personalizados
A veces, un recurso expone una acción personalizada que no se ajusta al estándar CRUD. Una acción personalizada siempre se invoca con POST (para recopilaciones de recursos y singulares) y su tipo de medio de solicitud es:
application/vnd.oracle.adf.action+jsonEl tipo de medio de respuesta es:
application/vnd.oracle.adf.actionresult+jsonPor ejemplo, en Oracle Sales Automation, el recurso leads de https://<crm_server:portNumber>/salesApi/resources/latest/describe/leads/ tiene una acción personalizada para convertir una oportunidad potencial en una oportunidad denominada: 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" ]
},Piense en una acción personalizada como una serie de pasos, un proceso o una combinación de diferentes operaciones CRUD para lograr un objetivo específico. En el ejemplo anterior, el cuerpo de solicitud de una acción personalizada debe transferir el "nombre" que va a ser ese nombre de acción personalizada (es decir, convertLeadToOpty) y, opcionalmente, una matriz de parámetros de entrada para la acción personalizada (es decir, leadId).
Normalmente, el cuerpo JSON de la solicitud 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"
]
}El objeto de respuesta JSON contiene el resultado del método custom action en el campo "results".
Acerca del soporte por lotes
Para mejorar el rendimiento, se pueden combinar varias operaciones en una sola solicitud HTTP enviando un objeto JSON que contenga un campo denominado "partes" como matriz de objetos. Cada objeto de la matriz contiene un ID único, una ruta relativa al recurso, una operación y, opcionalmente, una carga útil.
El esquema JSON de la solicitud HTTP es:
{
"$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"
]
}
Por ejemplo, la siguiente solicitud recuperará un empleado existente y actualizará otro empleado:
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 respuesta de la solicitud anterior utiliza el mismo tipo de medio que la solicitud y devuelve un objeto JSON como:
{"parts":[
{
"id":"part1",
"path":"/latest/hremployees/101",
"operation":"get",
"payload" : {
"EmployeeId" : 101
…
},
{
"id" : "part2",
"path" : "/latest/hremployees/102",
"operation" : "update",
"payload" : {
"EmployeeId" : 102,
} ]}Prueba de una solicitud de servicio web de Oracle Sales Automation RESTful
Para probar una API RESTful y obtener los datos necesarios, puede utilizar la herramienta de línea de comandos cURL para transferir datos desde o hacia un servidor mediante uno de los protocolos soportados, como HTTP o HTTPS.