Quickstart: Get started with Connectors

You're viewing Apigee X documentation.
View Apigee Edge documentation.

This tutorial shows you how to use Apigee Integration and Connectors to create a sample integration that triggers the publication of a Cloud Pub/Sub message.

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 Cloud 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:

    • Create a new Apigee instance. New Apigee instances can be provisioned with the Provisioning UI.

      Supported regions for Connectors include:

      • us-central1
      • us-east1
      • us-west1
      • europe-west1
      • asia-east1
    • Confirm that the Apigee Integration and Connectors features are entitled to your Apigee subscription.
    • 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}}}'
  • Before creating a Cloud Pub/Sub connection to use in your integration, do the following:
  • 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 Connector Platform API

    If these services have not been enabled for your project previously, you will be prompted to enable them before using the Connectors UI.

    Create a Cloud Pub/Sub connection

    To configure a Connection:

    1. In the Cloud console, go to Apigee > Connectors page and select or create a Cloud project.

      Go to the Connections page

    2. Click + CREATE NEW to open the Create Connection page.
    3. Configure the connection:
      1. In the Create Connection section, complete the following:
        • Connector: Select the Connector type from the drop down list of available Connector types. For this example, select gcp > pubsub.
        • 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, add a Description of the connection instance.
        • Project ID: Enter the of the Google Cloud project where the Cloud Pub/Sub instance resides.
        • Topic ID: Enter the name of the Cloud Pub/Sub topic where the message should be published.
        • 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.
        • Click NEXT.
      3. Authentication: Provide authentication credentials for your connection instance, if required. The Cloud Pub/Sub connection does not require authentication configuration.
      4. Click NEXT.
      5. Review: Review your connections's configuration details. In this section, the Connection details and Authentication details of the new connection are displayed for your review.
    4. Click Create.

    Create a new integration

    To create a new integration, perform the following steps:

    1. Go to the Apigee UI and sign in to the same project where your connection was created.
    2. Click Develop > Integrations.
    3. Click CREATE NEW.
    4. Enter a name and description in the Create Integration dialog.
    5. Click Create to open the integration designer.

    Configure a 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.

    Add an API Trigger

    To add an API Trigger to a new or existing integration, follow the steps below:
    1. In the integration designer, click + Add a task/trigger to view the task and trigger selection dialog.
    2. Click Triggers to view the available triggers.
    3. Drag the API Trigger element to the designer.

    Configure the API Trigger

    Click the API Trigger element in the integration designer to view the trigger configuration pane.

    The configuration panel displays the Trigger ID, which is a machine-generated ID in the format api_trigger/TRIGGER_NAME. No further configuration is required for this trigger.

    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 Cloud Pub/Sub connection

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

    1. Go to the Apigee UI and sign in.
    2. Select your organization using the drop-down menu in the upper left corner of the UI.
    3. Click Develop > Integrations.
    4. Search for or select the integration to edit from the Integrations list and click to open the integration designer.
    5. Click +Add a task/trigger > Tasks to view the list of available tasks.
    6. Drag the Connectors task element to the integration designer.
    7. Click the Connectors task element on the designer to view the Connectors task configuration pane.
    8. 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.
    9. On the Configuration tab in the Configuration section, click the Configure task button to open the Configure connector task pane.
      1. In the Connection column, choose the Cloud Pub/Sub connection you created in a previous step from the list of available connections.
      2. 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 Cloud 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 Cloud Pub/Sub connection has one available Action
      3. Click Done to complete the connection configuration and close the pane.
    10. The Connectors task configuration pane for a Cloud 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.
    11. 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.

    12. 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:

    1. Click the Publish button in the integration designer toolbar.
    2. 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.
    3. Click Test integration.
    4. Upon success, the Test Integration window will display a success message, along with the value of the integration's input and output variable payloads.
    5. 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.
    • 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 Cloud Pub/Sub connection in Apigee Integration!

    What's next