Acessar Dados do Oracle Sales Automation Usando Serviços RESTful
Cada API contém objetos padrão do Oracle Sales Automation e cada objeto é associado a um Recurso ou a uma Coleta de Recursos REST. Por exemplo, na API RESTful, o ponto final do recurso Opportunities é usado para rastrear informações sobre uma venda potencial. No entanto, antes de usar os web services do Oracle Sales Automation RESTful, você deve levar em consideração os requisitos de segurança para obter acesso e também identificar quais web services usar, juntamente com seus métodos suportados correspondentes e estruturas de payload esperadas.
Sobre recursos nas APIs do Oracle Sales Automation RESTful
O Oracle Sales Automation fornece um conjunto de recursos REST para objetos padrão e personalizados.
Um conceito importante em qualquer API RESTful é o recurso. Um recurso é um objeto com um tipo (por exemplo, Oportunidades), dados associados, relacionamentos com outros recursos e um conjunto de métodos que operam nele. Esses recursos são organizados de forma hierárquica que inclui:
-
Recurso raiz: Corresponde a um objeto lógico, como uma Oportunidade ou um Lead.
-
Sub-recurso(s): São recursos que pertencem a um recurso pai; por exemplo, um contato para uma oportunidade.
-
Recurso Lista de Valores: Uma lista de valores válidos que podem ser usados ao definir um valor para um campo. Há dois tipos: Pesquisa (lista estática) ou Dinâmica (com base no contexto).
Na API RESTful do Oracle Sales Automation, há dois tipos de recursos: um único recurso ou um recurso de coleta. Um único recurso pode representar uma única entidade, como um funcionário ou uma ordem de compra, enquanto um recurso de cobrança pode ser mais abrangente, como uma lista de funcionários ou uma lista de ordens de compra que podem ser paginadas.
Sobre o Suporte REST para Objetos Personalizados
O Oracle Sales Automation inclui objetos padrão que atendem a muitas necessidades e cenários de negócios. No entanto, além dos objetos padrão, você pode usar a ferramenta Application Composer para criar objetos personalizados de nível superior e objetos personalizados filhos se tiver uma necessidade de negócios exclusiva.
O Application Composer é uma ferramenta baseada em navegador que analistas de negócios e administradores (não apenas desenvolvedores) podem usar para personalizar o Oracle Sales Automation. Ao usar essa ferramenta, você pode fazer os tipos de alterações no modelo de dados que no passado foram feitas apenas por desenvolvedores. Na ferramenta Application Composer, você pode fazer alterações instantaneamente e elas ficam imediatamente disponíveis para uso sem precisar acessar novamente o aplicativo. Isso inclui a criação de Objetos Personalizados que podem ser adicionados à API do Oracle Sales Automation RESTful.
Dicas de Desempenho
Para obter o melhor desempenho das APIs REST do Oracle Fusion Sales Cloud, siga estas dicas.
- Consulte apenas os dados necessários.
- Consulte apenas os dados, não os metadados.
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=trueProcurar Recursos RESTful Usando Pontos Finais "Descrever"
Você pode obter detalhes específicos sobre as diferentes APIs RESTful do Oracle Sales Automation enviando uma solicitação HTTP GET que retorna um objeto JSON contendo informações de recursos e metadados complementares.
Obter os Pontos Finais do Serviço para Web Services RESTful
Você pode inferir o nome de um ponto final do Web Service do Oracle Sales Automation RESTful especificando o nome do serviço em vez da palavra-chave "describe" no URL da API.
Sobre Operações REST e Estruturas de Carga Útil
O serviço Web RESTful para cada objeto padrão do Oracle Sales Automation fornece várias operações de criação, leitura, atualização e exclusão (CRUD).
Você pode executar os seguintes métodos padrão para interagir com um recurso singular ou com uma coleção de recursos por meio de seus URLs:
| Método | Disponível para um Recurso Singular | Disponível para uma coleção de recursos |
|---|---|---|
| Get | S | N |
| Post | N | S |
| Patch | S | N |
| Excluir | S | N |
Sobre o Método Get
Use esse método para consultar e recuperar informações. No entanto, os parâmetros usados na consulta para refinar a pesquisa ou restringir os resultados em um recurso singular são diferentes daqueles usados em uma coleção de recursos.
Parâmetros para Recursos Singulares e de Coleta
Os seguintes parâmetros são usados no método para consultar um recurso singular, bem como um recurso de coleta:
| Parâmetro | Formatar | Descrição |
|---|---|---|
expand |
ou
|
Retorna o recurso pai, incluindo seus filhos. Por padrão, não retorna nenhum filho. |
fields |
fields=<FieldName1>,<FieldName2>... |
Selecione somente determinados campos cujas informações são exigidas. |
onlyData |
ou
|
Recupere apenas dados e não URLs de recursos. Por padrão, todos os URLs filhos do recurso são retornados. |
Parâmetros para Recursos de Coleta
Um método GET para recurso de coleta usa os parâmetros discutidos acima, bem como os seguintes parâmetros:
| Parâmetro | Formatar | Descrição |
|---|---|---|
limit |
|
Um número inteiro maior que 0 que especifica o número máximo de itens retornados pelo servidor. Se nenhum valor limite for especificado, o servidor usará um valor padrão. |
offset |
offset=<Integer> |
Um valor inteiro que especifica o índice do primeiro item a ser retornado. O índice de deslocamento começa em 0. |
q |
|
Especifique uma condição de filtro para restringir os itens retornados na coleção. O valor desse parâmetro de consulta contém uma ou mais expressões separadas por ";". Por exemplo, Operadores compatíveis:
Caracteres especiais:
|
totalResults |
ou
|
Um valor booliano que especifica se o número total de itens que correspondem ao parâmetro de consulta "q" deve ser retornado.
|
orderBy |
|
Especifica a ordem dos itens retornados na carga útil da resposta. O valor do parâmetro de consulta é uma string separada por vírgulas de nomes de campo, cada um opcionalmente seguido por dois-pontos e a palavra-chave Se não for especificado, o servidor retorna itens em ordem crescente. |
finder |
|
Usa uma "consulta" predefinida que tem seus próprios parâmetros especiais. Por exemplo, o recurso |
dependency |
|
Usado para recursos da Lista de Valores em cascata. Por exemplo, se um recurso Location tiver um campo State, esses valores serão derivados de outro recurso States que retorna uma lista de Estados para um País específico (local). Se, por exemplo, Local for: EUA e Estado for CA. O recurso Estados contém uma lista de todos os Estados Unidos, mas se o usuário na página da web alterar a localidade para o Brasil, a maneira de recuperar todos os estados brasileiros seria com uma chamada como esta:
|
Sobre o método Post
Use este método para criar um novo item. O cabeçalho do tipo de mídia da solicitação é:
application/vnd.oracle.adf.resourceitem+jsonPor exemplo, para criar uma nova oportunidade no recurso Opportunities, a solicitação passa o novo parâmetro de nome da Oportunidade em um objeto JSON:
{
"Name" : "New Opportunity Name"
}O corpo da resposta do objeto JSON retornado pela solicitação POST seria algo assim:
{
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"
…
}Sobre o Método de Patch
Use este método para fazer atualizações parciais em um recurso. Somente os campos contidos no corpo da solicitação serão atualizados.
O tipo de mídia da solicitação é:
application/vnd.oracle.adf.resourceitem+jsonPor exemplo, para atualizar uma Oportunidade existente do recurso Oppurtunities, a solicitação HTTP PATCH passa o seguinte objeto JSON como o corpo da solicitação:
{
"Name": "Opportunity Name Updated"
}A resposta desta solicitação é um objeto JSON semelhante 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"
…
}Sobre o Método Delete
Use este método para excluir um recurso. Não requer um corpo de solicitação.
Por exemplo, para excluir um objeto Oportunidade do recurso Opportunities, a solicitação DELETE precisa ser feita diretamente para o URI do recurso Opportunity filho a ser excluído, sem especificar nenhum parâmetro para ele:
https://<crm_server:PortNumber>/salesApi/resources/latest/opportunities/<OpportunityNumber>
Sobre os Métodos de Ação Personalizados
Às vezes, um recurso expõe uma ação personalizada que não se encaixa no padrão CRUD. Uma ação personalizada é sempre chamada com POST (para coleções singulares e de recursos) e seu tipo de mídia de solicitação é:
application/vnd.oracle.adf.action+jsonO tipo de mídia de resposta é:
application/vnd.oracle.adf.actionresult+jsonPor exemplo, no Oracle Sales Automation, o recurso leads em https://<crm_server:portNumber>/salesApi/resources/latest/describe/leads/ tem uma ação personalizada para converter um lead em uma oportunidade chamada: 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" ]
},Pense em uma ação personalizada como uma série de etapas, um processo ou uma combinação de diferentes operações CRUD para atingir um objetivo específico. No exemplo acima, o corpo da solicitação de uma Ação Personalizada deve informar o "nome" que será esse nome de ação personalizada (ou seja, convertLeadToOpty) e, opcionalmente, um array de parâmetros de entrada para a ação personalizada (ou seja, leadId).
Em geral, o corpo JSON da solicitação POST contém:
{
"$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"
]
}O objeto de resposta JSON contém o resultado do método de ação personalizada no campo "resultados".
Sobre o suporte em lote
Para melhorar o desempenho, várias operações podem ser combinadas em uma única solicitação HTTP enviando um objeto JSON contendo um campo chamado "partes" como uma matriz de objetos. Cada objeto dentro do array contém um id exclusivo, um caminho relativo para o recurso, uma operação e, opcionalmente, um payload.
O esquema JSON da solicitação 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"
]
}
Por exemplo, a seguinte solicitação extrairá um funcionário existente e atualizará outro funcionário:
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
}
}
]
}
A resposta da solicitação anterior usa o mesmo tipo de mídia da solicitação e retorna um 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,
} ]}Testar uma solicitação de serviço Web do Oracle Sales Automation RESTful
Para testar uma API RESTful e obter os dados necessários, você pode usar a ferramenta de linha de comando cURL para transferir dados de ou para um servidor usando um dos protocolos suportados, como HTTP ou HTTPS.