搜索

此内容没有您所选择的语言版本。

Chapter 14. Connecting to OData

download PDF

Open Data Protocol (OData) is a standard for building and consuming REST APIs. An OData service provides services to clients, such as Fuse Online, through OData-compliant HTTP requests. A Fuse Online integration can obtain entities from an OData service, and can update, create, or delete entities managed by an OData service. To do this, create an OData connection, and then add it to an integration.

It is assumed that you are familiar with the OData specification.

Details are in the following topics:

Important

The OData connector is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/.

14.1. Creating a connection to an OData service

In an integration, to obtain entities from an OData service, or to update, create or delete entities that are managed by an OData service, you must first create a connection to that OData service.

Prerequisite

  • You must know the base URL for the OData service that you want to connect to.
  • If that service uses authentication then you must have the required credentials, and, if required, an SSL certificate. However, most OData services are public and do not require authentication.

Procedure

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display connectors.
  3. Click the OData connector.
  4. To configure the connection:

    1. In the Service Root URL field, enter the base URL for the OData service that you want to access.
    2. In the User Name field, if the service uses basic authentication, then enter your user name.
    3. In the Password field, if the service uses basic authentication, then enter your password.
    4. In the Server Certificate field, if the service requires it, paste the content of an SSL certificate.

      Typically, a public OData service does not require a certificate in addition to the certificates provided by the browser. However, for an internal OData service, you might have created your own SSL certificate and self-signed it. Since this certificate is not trusted by a certificate authority, connections to your OData service would fail. To enable connections, paste the self-signed certificate here.

      One way to get the certificate is to load the service in a browser. The steps after that depend on which browser you are using, but it will be something like the following: click the Not secure padlock symbol next to the address bar, then click View Certificate, export the displayed certificate to a file, copy the certificate, and paste it into this field.

  5. Click Validate. Fuse Online immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the input parameter(s) and try again.
  6. If validation is successful, click Next.
  7. In the Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter OData North.
  8. In the Description field, optionally enter any information that is helpful to know about this connection.
  9. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that OData North appears as a connection that you can choose to add to an integration.

Next step

Add your OData connection to an integration.

14.2. Triggering an integration when polling returns data from an OData service

To trigger execution of an integration upon obtaining data from an OData service, add an OData connection to a simple integration as its start connection. When the integration is running, the OData connection polls the service at intervals that you specify. When the connection finds data that satisfies the connection configuration, the connection passes the data to the next step in the integration.

Prerequisite

You created an OData connection.

Procedure

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the OData connection that you want to use to start the integration.
  4. On the Choose an Action page, click the Read action.
  5. To configure the Read action:

    1. In the Resource Collection field, select the name of the OData resource that you want to query. Fuse Online fetches data from the OData service to provide a list of available resource collections.
    2. In the Entity Key Predicate field, to obtain a particular entity, identify the entity that you want by specifying its key predicate. For example, specify something like UserName='Bob' or Categories(1). To obtain multiple entities, leave this field blank.
    3. In the Query Options field, enter a query that you want to apply to the resource. Use OData syntax. For example, $filter=startswith(name, 'N') returns a message for each entity in the resource that has a name field that starts with N.

      You can specify both Entity Key Predicate and Query Options. If you do, the OData service obtains the specified entity and applies the query to that entity. For example, suppose that you set Entity Key Predicate to UserName='russellwhyte'/Emails and you set Query Options to $filter=contains($it,'example'). The connection creates a request that looks something like this:

      https://services.odata.org/TripPinRESTierService/People(UserName='russellwhyte')/Emails?$filter=contains($it, 'example')

      The service returns all email addresses for Russell Whyte that contain the domain example.

    4. Select the Filter Old Results checkbox to obtain a particular message only once.
    5. Select the Split Results checkbox if you want the connection to return individual messages rather than a collection of messages.

      Fuse Online also provides discrete split and aggregate steps, which you can add to a flow. If you want to process individual messages in one or more steps and then aggregate the messages into a collection, do not select the Split Results checkbox. Instead, leave the checkbox empty and then add a split step to the flow after this connection. A split step is required if you want an aggregate step in the flow.

    6. In the Interval Before Polling Starts field, accept the default of 1 second, or enter the length of time that you want to elapse before the connection starts to poll the OData service.
    7. In the Delay field, accept the default of 30 seconds, or enter the interval at which you want the connection to poll the OData service.
    8. In the Backoff Idle Threshold field, accept the default of 1 or enter an integer that indicates the number of consecutive polls that can return no data. After this number of polls, the connection increases the interval between subsequent polls. The connection determines the new length of the polling interval by multiplying the Delay value by the Backoff Multiplier value.

      For example, suppose that the polling interval (the Delay value) is the default of 30 seconds, Backoff Idle Threshold is set to 5, and Backoff Multiplier is set to 12. After 5 consecutive polls that return no data, the connection waits 360 seconds (30 x 12) before polling again. The connection continues to poll every 360 seconds until a poll returns data. After a poll returns data, the connection resumes polling every 30 seconds.

    9. In the Backoff Multiplier field, accept the default of 1 or enter an integer that indicates the multiplier for increasing the polling interval if the value set for the Backoff Idle Threshold is reached.

      If you accept the default of 1 for the Backoff Multiplier, then the connection continues to poll at the specified interval no matter how many consecutive polls return no results.

      The values that you specify for Backoff Idle Threshold and Backoff Multiplier are useful for reducing CPU overhead since the connection can automatically poll less often during quiet periods.

  6. Click Done.

Result

The connection appears in the integration flow as the integration’s start connection.

During execution, what the connection returns depends on what you specified in the Entity Key Predicate and Query Options fields. The OData connection can return:

  • A collection of entities or a collection of entity properties

    For example, this might be all Person entities in the resource, or perhaps all Age properties for all Person entities. The connection returns the collection in one message. Fuse Online executes each subsequent step in the flow once for the collection. However, when you configure the Read action, if you select Split Results, then the connection returns each entity or each property in its own message. Fuse Online executes each subsequent step in the flow once for each message.

  • An entity or an entity property

    For example, this might be the Person entity whose UserName property is Bob, or perhaps the Age property for the Person entity whose UserName is Bob. The connection returns the entity or the entity property in a message that it passes to the next step in the flow.

Next steps

Add the integration’s finish connection and any other connections that you want to include in the integration. When the integration contains all the connections that are needed, if the OData connection returns a collection, consider whether you need to add a split step after the OData connection. An integration usually needs to map the data returned by the OData connection to fields that a subsequent connection in the flow can use. Sometimes you can map a collection, but more often you need to split the collection in order to map to the target fields.

After the OData connection, add a data mapper step to the flow. Exactly where in the flow depends on what you want the flow to do. For example, after the OData connection, you might add a basic filter step and then add a data mapper step.

14.3. Updating, creating, and deleting data that is managed by an OData service

In an integration, you can update a resource that is managed by an OData service in the middle of a flow or to finish a simple integration. To do this, add an OData connection to the middle of a flow or as a simple integration’s finish connection.

Prerequisites

  • You created an OData connection.
  • You are creating or editing an integration and Fuse Online is prompting you to choose a step. Or, Fuse Online is prompting you to choose a finish connection.

Procedure

  1. Click the OData connection that you want to use. Note that when an OData connection updates or deletes an entity, the connection does not return anything. When the OData connection creates an entity, the connection returns the new entity.
  2. On the Choose an Action page, click the action that you want the connection to perform:

    • Create adds an entity to an OData resource.
    • Delete removes an entity from an OData resource.
    • Update changes an entity that is in an OData resource.
  3. To configure the action, select the OData resource that you want to update.

    It is important for you to have an understanding of how the OData resource that you are updating is set up. The backing data source for an OData service determines the rules for updates and resolving conflicts. For example, suppose an OData connection tries to create a new entity but an entity with that predicate key already exists. The OData service might overwrite the existing entity, or it might update some fields in the existing entity, or it might ignore the operation. It is up to you to know how the OData service behaves in this situation.

  4. Click Done.

Result

The connection appears in the integration flow in the location where you added it.

Next steps

Add a data mapper step before the OData connection. You must map source fields that provide the data that is required to create a new entity, to update an entity, or to delete an entity. If you map a collection to a target field, the default behavior is that the content in the last element that is in the source collection is mapped to the target field.

Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

© 2024 Red Hat, Inc.