Configure your Eventarc source

Eventarc lets you asynchronously deliver events from third-party providers to interested subscribers. For details, see Third-party events in Eventarc.

After registering as a provider, to configure your service with Eventarc you must complete the following steps.

Enable APIs

Before configuring your service, ensure that you have enabled the Eventarc APIs:

gcloud services enable \
eventarc.googleapis.com \
eventarcpublishing.googleapis.com

Establish a channel activation process

As part of establishing a channel connection, you must provide subscribers with a way of conveying their channel names and activation tokens to you. This can be done using a form on your website, an app, or through an API. Note that providing multiple ways for your customers to do this might benefit them, but you are only required to demonstrate one working method to validate your event source.

You can provide additional configuration options once the channel is conveyed. For example, your subscribers can have the option of specifying filters (through an attribute, or other provider-specific criteria) to route the events that the subscriber can receive through their channel.

Create a channel connection

When you receive a channel name and activation token from a customer, use this information to activate the channel and create an explicit connection to the channel before you publish events to it. This is done by creating a ChannelConnection resource in your publisher project using the Eventarc API. For more information, see the reference page for the channelConnections.create method.

The ChannelConnection is a persistent resource that only needs to be created once for each subscriber channel.

gcloud eventarc channel-connections create CHANNEL_CONNECTION \
    --project PUBLISHER_PROJECT_ID \
    --location REGION \
    --channel CHANNEL_NAME \
    --activation-token ACTIVATION_TOKEN

Replace the following:

CHANNEL_CONNECTION: the channel connection ID or fully qualified identifier for the channel connection.
PUBLISHER_PROJECT_ID: the publisher project ID specified during registration. Other project IDs will be rejected.
REGION: must be a supported region and match that of the associated subscriber channel.
CHANNEL_NAME: the absolute path to the channel. For example: projects/subscriber-gcp-project-id/locations/us-central1/channels/test-channel-123
ACTIVATION_TOKEN: the string generated by Eventarc when a subscriber creates a channel.

Every ChannelConnection has a unique name with the following format:

projects/PUBLISHER_PROJECT_ID/locations/REGION/channelConnections/CHANNEL_CONNECTION_ID

Publish events

Once a ChannelConnection exists, you can publish events directly to that ChannelConnection using the Eventarc Publishing API. There are several ways you can do this, including through a client library. Contact us at eventarc-integration@google.com and we can provide you with a client library sample for this purpose.

Publish using the gcloud CLI

You can publish events to a channel connection using the gcloud CLI.

gcloud eventarc channel-connection publish CHANNEL_CONNECTION \
    --event-id=EVENT_ID \
    --event-type=EVENT_TYPE \
    --event-attributes=EVENT_ATTRIBUTE \
    --event-source=gcloud \
    --event-data="{ EVENT_DATA }"

Replace the following:

EVENT_ID: the event ID
EVENT_TYPE: the event type
EVENT_ATTRIBUTE: event attributes
EVENT_DATA: any arbitrary, valid JSON data

Example:

gcloud eventarc channel-connection publish helloworld-channel-connection \
    --event-id=12345 \
    --event-type=mycompany.myorg.myproject.v1.myevent \
    --event-attributes=someAttr=foo \
    --event-source=gcloud \
    --event-data="{\"message\" : \"Hello world from gcloud\"}"

You should see an Event published successfully message.

Publish using curl

You can publish events to a channel connection using curl commands. The following example uses an access token generated by the gcloud CLI.

Example:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H "X-Goog-User-Project: {publisher_project_id}" -X POST -d '{
  "channelConnection": "projects/{publisher_project_id}/locations/us-central1/channelConnections/test-connection-123",
  "events": [
    {
      "@type": "type.googleapis.com/io.cloudevents.v1.CloudEvent",
      "id": "12345",
      "source": "//companyname/example",
      "specVersion": "1.0",
      "type": "{event_type}",
      "attributes": {
        "time": {
          "ceTimestamp": "1970-01-01T00:00:01Z"
        },
        "datacontenttype": {
          "ceString": "application/json"
        }
      },
      "textData": "{\"message\": \"test message 123\"}"
    }
  ]
}' https://eventarcpublishing.googleapis.com/v1/projects/{publisher_project_id}/locations/us-central1/channelConnections/test-connection-123:publishEvents

Note that the event_type should be one of the event types that you registered as a provider and must follow this format: PROVIDER_ID.PROVIDER_SPECIFIED_TYPE_NAME.VERSION.ACTION.

For example: companyname.fooProcess.v1.resourceUpdated

The PROVIDER_SPECIFIED_TYPE_NAME can include multiple segments (for example, foo.processA) or can be omitted if not required. If you don't supply any event types, the default event type of PROVIDER_ID.v1.event is used.

Publish using client libraries

You can publish events to a channel connection using client libraries. Contact us at eventarc-integration@google.com and we can provide you with a client library sample for this purpose.

Delete the `ChannelConnection` resource

If a subscriber wants to unsubscribe to events, the provider must deactivate the channel in the subscriber project by deleting the ChannelConnection resource. The subscriber can confirm that the subscription has been deactivated in the Eventarc interface.

For more information, see the reference page for the channelConnections.delete method.