Get started with Apigee Integration and Pub/Sub connection

This tutorial shows you how to use integrations and connectors to create a sample integration that triggers the publication of a Cloud Pub/Sub message. The tutorial assumes that you have a working knowledge of Apigee Integration.

In this example, calling an API endpoint triggers the publication of a message to a Cloud Pub/Sub topic. The steps below describe how to configure the API trigger and Pub/Sub connection required to run a successful integration.

Before you begin

Before beginning this tutorial, confirm your Google Cloud login credentials and organization details. This information is required to access connectors UI. Your Apigee credentials are required to access the connectors task within the Apigee integration designer. Additional prerequisite steps are described below:

Before creating a connection for the first time, complete the following steps:
Note: These steps are only required if you are enabling the Apigee Integration and Connectors add-ons for the first time for use with Apigee.
1. Create a new Apigee instance. New Apigee instances can be provisioned with the Provisioning UI.
  For the list of regions supporting connectors, see Supported connector regions.
2. Confirm that the Apigee Integration and connectors features are entitled to your Apigee subscription.
3. Enable the Apigee Integration and connectors features using the following command:
```
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H \
"content-type:application/json" \
"https://apigee.googleapis.com/v1/organizations/PROJECT_ID:setAddons" -XPOST \
-d '{"addonsConfig": {"integrationConfig": {"enabled": true}, "connectorsPlatformConfig": {"enabled": true}}}'
```
  Warning: When you run an add-on command, it overwrites any existing add-ons. Therefore, if you have any existing add-ons, include them in the add-on command. Otherwise, the command to enable Apigee Integration and connectors will disable all other add-ons in your existing organization. And if an add-on is disabled, Apigee deletes all configurations of the add-on (feature). For example, if you disable the Integrations add-on, all integrations are deleted.
4. If you don't have a service account, create a service account.
  A service account is a special type of Google account intended to represent a non-human user that needs to authenticate and be authorized to access data in Google APIs. If you don't have a service account, you must create a service account. For more information, see Creating a service account.
Before creating a Pub/Sub connection to use in your integration, do the following:
- Create a Pub/Sub topic and add a subscription, as described in the Cloud Pub/Sub Quickstart: Using the console.
- Grant permission to publish to your Pub/Sub topic. For example, you can use the roles/pubsub.publisher role to publish to topics. For more on Pub/Sub roles, see Access Control.
- Generate a key for the service account. The JSON key file is used in a later step to configure the Pub/Sub connection.

Enable required services

Connectors requires that you enable the following Google services:

Name	Title
`apigee.googleapis.com`	Apigee API
`secretmanager.googleapis.com`	Secret Manager API
`connectors.googleapis.com`	Connectors API

If these services have not been enabled for your project previously, you are prompted to enable them when creating the connection in the Create Connection page.

Create a Pub/Sub connection

To configure a Connection:

In the Cloud console, go to the Integration Connectors > Connections page and then select or create a Google Cloud project.
Go to the Connections page
Click + CREATE NEW to open the Create Connection page.
Configure the connection:
1. In the Create Connection section, complete the following:
  - Connector: Select Cloud Pub/Sub from the drop down list of available Connectors.
  - Connector version: Select the Connector version from the drop down list of available versions.
  - In the Connection Name field, enter a name for the Connection instance.
    Connection names must meet the following criteria:
    - Connection names can use letters, numbers, or hyphens.
    - Letters must be lower-case.
    - Connection names must begin with a letter and end with a letter or number.
    - Connection names cannot exceed 63 characters.
  - Optionally, enter a Description for the connection instance.
  - Service Account: Select a service account that has the required roles.
  - Project ID: The ID of the Google Cloud project where the Pubsub instance resides.
  - Topic ID: The name of the topic the message should be published to.
  - Optionally, click + ADD LABEL to add a label to the Connection in the form of a key/value pair.
  - Click NEXT.
2. Location: Choose the location for the connection.
  - Select a location where Apigee is available from the Region drop-down list.
    Supported regions for connectors include:
    For the list of all the supported regions, see Locations.
  - Click NEXT.
3. Authentication: Authentication types supported by the Cloud Pub/Sub connection:
  - AUTH_TYPE_UNSPECIFIED
  Enter the details based on the authentication you want to use.
  - AUTH_TYPE_UNSPECIFIED
4. Click NEXT.
5. Review: Review your connection and authentication details.
Click Create.

Create a new integration

To create a new integration, perform the following steps:

Go to the Apigee UI and sign in to the same project where your connection was created.
Click Develop > Integrations.
Click CREATE NEW.
Enter a name and description in the Create Integration dialog.
Note: Integration names must meet the following requirements:
- Names must start and end with letters or numbers.
- Names cannot contain spaces or more than one dash or underscore in a row.
Click Create to open the integration designer.

Add an API trigger

Triggers are required to start the sequence of tasks that make up an integration. Any available trigger can be used to start an integration. This tutorial uses the API trigger to directly invoke execution of the integration.

To add an API trigger to a new or existing integration, follow the steps below:

In the integration designer, click + Add a task/trigger to view the task and trigger selection dialog.
Click Triggers to view the available triggers.
Drag the API trigger element to the designer.

No further configuration is required for this trigger. To view the API trigger ID, click the API trigger element in the integration designer. The configuration panel displays the Trigger ID, which is a machine-generated ID in the format api_trigger/TRIGGER_NAME.

Add and configure tasks

A task is an executable set of steps that can take variables as inputs and generate variables as outputs. As with triggers, any available task can be used in an integration.

This tutorial uses the Connectors task. Configuration details for the task are described in the steps below.

Configure the Create a Connectors task with a Pub/Sub connection

To configure the Connectors task in Apigee Integration to use the Pub/Sub connection:

Go to the Apigee UI and sign in.
Select your organization using the drop-down menu in the upper left corner of the UI.
Click Develop > Integrations.
Search for or select the integration to edit from the Integrations list and click to open the integration designer.
Click +Add a task/trigger > Tasks to view the list of available tasks.
Drag the Connectors task element to the integration designer.
Click the Connectors task element on the designer to view the Connectors task configuration pane.
Optionally, click the to edit the task name. This enables you to change the task name from the generic Connectors to a meaningful name for your integration.
On the Configuration tab in the Configuration section, click the Configure task button to open the Configure connector task pane.

In the Connection column, choose the Pub/Sub connection you created in a previous step from the list of available connections.
Once a connection is chosen, the Type column appears. For this example, select Actions and then publishMessage from the list of available actions.
- An Entity can be thought of as an object, or a collection of properties, in the connected application or service, that can be exposed to an integration through the Connector interface. The Pub/Sub connection does not expose any entities.
- An Action is a first class function that is made available to the integration through the Connector interface. Functions are defined in the connected application or service and define a change or series of changes that can be made to an entity or entities. The Pub/Sub connection has one available Action
Click Done to complete the connection configuration and close the pane.

The Connectors task configuration pane for a Pub/Sub connection also displays Task Input variables and Task Output variable automatically generated by the Entity and Operation or Action selected in the previous step for use in the connection. These variables are accessible as inputs to subsequent tasks or conditionals configured in the current integration. To configure the Task Input:
1. Click on the Connector input payload variable pill to open the Configure Variable pane.
2. In the Default Value field, enter the following text: {"message": "test message from integration platform"}.
3. Select the Use as an input to integration checkbox.
4. Click Save.
You can configure various retry strategies to handle errors in a task. The retry strategies allow you to specify how to rerun the task in case of an error. For more information, see Error handling strategies.
Add an edge connection from the API trigger element to the Connectors element by hovering over a control point on the API trigger element, then clicking and dragging a line to a control point on the Connectors task element. The control points and edge line will turn yellow. The edge denotes the flow of control from the API trigger task to the Connectors task.

Test the integration

To test the new integration:

Click the Publish button in the integration designer toolbar.
Click Test to trigger and run the integration. This will open the Test Integration window, which displays the input variable (message) that you set in a previous step. If desired, the input variable can be modified here.
Click Test integration.
Upon success, the Test Integration window will display a success message, along with the value of the integration's input and output variable payloads.
Click Close to exit the Test Integration window.

To verify the success of your integration:

Go to the Pub/Sub page.
Go to Pub/Sub
Select your Pub/Sub topic and then click View messages to confirm receipt of the message sent by the integration.
Note: There may be a delay of up to several minutes before the message appears.
Inspect the Apigee Integration logs to view the status of a given integration. To view logs:
1. Click Logs in the toolbar of the integration designer.
2. On the Execution Logs page, you can view details about each attempt to run an integration. Each entry includes details for the execution attempt, including:
  - Integration name
  - Execution ID
  - Status
  - Start time
  - Duration
  - Integration ID
  - Trigger ID
3. Click the expander arrow (>) next to the executed integration to view an expanded list of tasks and variables in the integration, along with task status and variable payloads.

Congratulations! You just created and successfully tested a Pub/Sub connection in Apigee Integration!

What's next

See the list of supported connectors in Apigee.
Learn how to create and manage connections.