OData
Saiba mais sobre o conector OData e como usá-lo na Digibee Integration Platform.
O conector OData permite integrações com qualquer serviço compatível com OData (v4 ou v2), como SAP, Microsoft Dynamics 365, Business Central, Salesforce e feeds OData públicos, estendendo o REST engine da plataforma.
Ele monta requisições baseadas em padrões para consultar e manipular um entity set (coleção) OData, incluindo CRUD, query options server-driven ($filter, $select, $orderby, $top, $skip, $expand, $count), actions e functions bound/unbound e $batch.
Use este conector quando:
Você precisa ler ou gravar dados em um serviço OData que não tem um conector dedicado na Digibee.
Você quer controle explícito sobre a requisição OData (entity set, key, query options, actions,
$batch).Você está integrando SAP OData / SAP S/4HANA, Business Central, ou uma API OData personalizada.
OData vs. conectores específicos de fornecedor
Para o Microsoft Dynamics 365, use o conector Dynamics 365 (Customer Engagement/Dataverse) ou Dynamics 365 Finance & Operations. Ambos são versões especializadas do OData engine, com valores padrão específicos do produto e descoberta guiada de entidades.
Conceitos
Os termos abaixo aparecem ao longo dos parâmetros do conector, por isso é importante entendê-los antes de configurar uma requisição. Cada conceito corresponde a um campo específico que você vai preencher mais adiante.
Entity Set
A coleção que você está endereçando, por exemplo Customers. Ela se torna o primeiro segmento do path: /Customers.
Entity Key
Identifica um único registro. Pode ser um valor único (42, guid'…') ou uma chave composta (id1=val1,id2=val2). Representada como /Customers(42) ou /Customers(id1=val1,id2=val2).
Query options
Parâmetros server-driven: $filter, $select, $orderby, $top, $skip, $expand e $count.
Action / Function
Operações do lado do servidor. Uma operação bound tem como destino uma entidade ou coleção específica; uma operação unbound se aplica ao serviço como um todo. Actions usam POST; functions usam GET.
OData version
4.0 (padrão) ou 2.0. Determina os headers da requisição e como a resposta é interpretada: value, @odata.count e @odata.nextLink para a v4, ou d e d.results para a v2.
Parâmetros
A tabela abaixo lista todos os parâmetros de configuração do conector. Os parâmetros que suportam expressões Double Braces estão marcados com ✅ na coluna Suporta DB.
Alias
Um nome para a saída deste conector, para que você possa referenciá-la depois no fluxo com Double Braces.
String
✅
odata-01
Fail On Client Error (4xx)
Interrompe o pipeline em uma resposta 4xx.
Boolean
❌
false
Fail On Server Error (5xx)
Interrompe o pipeline em uma resposta 5xx.
Boolean
❌
false
Base URL
URL raiz do serviço OData. A barra final é normalizada.
String
✅
https://services.odata.org/V4/Northwind/Northwind.svc
—
Use Dynamic Account
Se ativado, o conector resolve a conta em tempo de execução. Se desativado, usa a conta configurada estaticamente abaixo.
Boolean
❌
false
—
Scoped
Se ativado, isola a conta armazenada de outros subprocessos. Não disponível para contas referenciadas em headers ou no corpo da requisição. Para saber mais, leia a documentação de Dynamic Accounts.
Boolean
❌
false
Use Dynamic Account está ativado
Account Name
Nome da conta definida no conector Store Account.
String
✅
N/A
Use Dynamic Account está ativado
Account
Conta usada para autenticar a requisição. Tipos suportados: Azure Key, Basic, API Key, OAuth Bearer, OAuth 2.0, AWS V4, custom auth header (e outros disponíveis na plataforma). Saiba mais sobre Contas.
Account
—
N/A
Use Dynamic Account está desativado
Parâmetros base
Estes parâmetros formam a base da requisição: Entity Set, OData Version e Operation. A Operation escolhida aqui determina quais parâmetros adicionais aparecem a seguir.
OData Version
4.0 ou 2.0. Determina os headers da requisição e a interpretação da resposta.
Select
❌
4.0
Entity Set
Nome da coleção OData, como Customers.
String
✅
N/A
Operation
A ação a ser executada. Ela define o formato da requisição. Veja as operações suportadas abaixo.
Select
❌
Query
Operações suportadas
O parâmetro Operation mapeia para uma requisição OData da seguinte forma:
Batch
POST
/$batch
multipart/JSON
Agrupa várias operações em uma única requisição.
Create
POST
/{EntitySet}
JSON
Cria um registro.
Custom Query
GET
/{EntitySet}?{$query}
—
Equivalente a Query. Use quando combinar parâmetros de query brutos e estruturados.
Delete
DELETE
/{EntitySet}({key})
—
Exclui um registro.
Get by ID
GET
/{EntitySet}({key})
—
Lê um único registro pela chave.
Invoke Action
POST
/{EntitySet}({key})/{Action} ou /{Action}
JSON
Invoca uma bound action (com key e entity set) ou uma unbound action.
Invoke Function
GET
/{EntitySet}({key})/{Function} ou /{Function}
—
Invoca uma bound ou unbound function.
Query
GET
/{EntitySet}?{$query}
—
Lê a coleção com query options.
Update
PATCH/PUT
/{EntitySet}({key})
JSON
Atualiza um registro, parcialmente (PATCH) ou totalmente (PUT).
Parâmetros comuns
Assim como os parâmetros base, estes se aplicam independentemente da operação escolhida. Eles são agrupados aqui por clareza, mesmo aparecendo depois dos campos específicos da operação nas configurações do conector.
Output Format
Controla o formato da resposta retornada ao pipeline. Values Only desempacota e retorna apenas o array value. Full Response retorna a resposta completa, incluindo os campos @odata.*. Single Entity retorna a primeira ou única entidade.
Select
❌
Values Only
Headers
Headers adicionais da requisição, como pares chave/valor.
Key/Value
✅
N/A
Parâmetros específicos por operação
Os parâmetros restantes aparecem apenas para determinadas operações, agrupados abaixo por finalidade.
Entity Key — usado por Delete, Get by ID, Invoke Action, Invoke Function e Update.
Entity Key
Chave simples ou composta.
String
✅
N/A
Action / Function Name — usado por Invoke Action e Invoke Function.
Action / Function Name
Nome da action ou function OData. Bound quando um Entity Set é definido, unbound caso contrário.
String
✅
N/A
Body — usado por Batch, Create, Invoke Action e Update.
Body
Payload JSON para Create e Update, parâmetros da action para Invoke Action, ou o payload do $batch.
JSON
✅
{}
Query parameters — usado por Custom Query e Query.
Filter ($filter)
Expressão de filtro OData, por exemplo Age gt 18 and City eq 'NY'.
String
✅
N/A
Select ($select)
Campos separados por vírgula a incluir na resposta.
String
✅
N/A
Order By ($orderby)
Ordena os resultados por uma ou mais propriedades, em ordem crescente ou decrescente. Por exemplo, Name asc, Created desc.
String
✅
N/A
Expand ($expand)
Entidades relacionadas a incluir inline.
String
✅
N/A
Top ($top)
Número máximo de registros a retornar. Sem limite artificial.
Number
✅
N/A
Skip ($skip)
Registros a pular (paginação).
Number
✅
N/A
Include Count ($count)
Inclui a contagem total na resposta.
Boolean
❌
false
Request Timeout (seconds)
Tempo máximo para a requisição HTTP.
Number
❌
30
—
Custom Query String
Parâmetros de query extras, adicionados literalmente (por exemplo, cross-company=true).
String
✅
N/A
—
Update Method
PATCH para uma atualização parcial, ou PUT para uma substituição completa.
Select
❌
PATCH
Operation é Update
Documentation
Campo opcional para descrever a configuração do conector e quaisquer regras de negócio relevantes.
String
❌
N/A
Tratamento da resposta
OData v4: O conector lê a coleção a partir de
value, a contagem total a partir de@odata.count, e os links de paginação a partir de@odata.nextLink.OData v2: O conector lê a coleção a partir de
d.results(oud).Output Format: Determina qual parte dessa resposta chega ao pipeline. Veja o parâmetro Output Format em OData API para os valores disponíveis.
Exemplos
Consulta com filter e select (v4)
Entrada (parâmetros do conector):
Saída (quando Output Format está definido como Values Only):
Create
Invocar uma bound action
Requisição resultante:
Limitações conhecidas
O conector não pagina automaticamente. Para obter páginas adicionais, siga o
@odata.nextLinkmanualmente (por exemplo, com um Loop) ou controle a paginação usando$tope$skip.Os payloads do
$batchprecisam estar bem formados de acordo com a versão OData do serviço de destino.A descoberta automática de entidades e campos a partir do
$metadataestá disponível apenas nos conectores Dynamics guiados. No conector OData genérico, o Entity Set é um campo de texto livre.
Erros comuns
400
Expressão $filter malformada ou sintaxe de key inválida.
401 / 403
Credenciais de conta ausentes ou inválidas, ou scope insuficiente para a requisição.
404
Nome de entity set ou key incorretos.
Ative Fail On Client Error (4xx) ou Fail On Server Error (5xx) para que o conector interrompa o pipeline quando esses erros ocorrerem.
Atualizado
Isto foi útil?