See the supported connectors for Application Integration.

Create a custom connector

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page describes how to create a custom connector. To understand what is a custom connector, see Custom connectors.

Note: A custom connector is a global resource; which means that once it's created, you can use it any of the locations supported for Application Integration.

To establish connectivity to your backend by using a custom connector, you need to do the following tasks:

1. Create a custom connector - In this task, you will define the contract between Application Integration and your endpoint (backend) by providing the endpoint's OpenAPI specification. Currently, only OpenAPI version 3.0 and all it's minor versions are supported. Specifying the specification, is a one time activity.
2. Create a custom connector connection - In this task, you will configure your backend's connection details, such as the hostname and authentication. For a specific custom connector, you can create as many connections as you require.

To understand the difference between a connector and a connection, see Connector versus connection.

Before you begin

Ensure the user creating the custom connector has any one of the following IAM roles:

• Custom Connector Admin
• Connectors Admin

Create a custom connector

As described in backend connectivity scenarios, custom connectors can have any of the following connectivity patterns:

• Direct connectivity to your backend's public endpoint.
• Indirect connectivity to your backend through an intermediary public endpoint.

The custom connector creation steps slightly vary for these two patterns.

Create a custom connector with direct connectivity

To create a custom connector with direct connectivity to your backend's endpoint, do the following steps:

Console

1. In the Console, go to the Application Integration > Custom connectors page, and then select or create a Google Cloud project.

   Go to the Custom connectors page

2. Click Create new to open the Create custom connector page.
3. In the Connector details section, set the following fields:
   1. Connector name: Enter a name for the connector.
   2. Display name: Enter a display name for the connector.
   3. Description: Enter a description.
   4. Custom connector type: Select the custom connector type.
   5. Service account: Select a service account that has the required roles.
4. Click Next.
5. In the Connector specification section, enter the URL of your backend's Open API specification in the Specification URL field, and then click Next. For example, https://petstore3.swagger.io/api/v3/openapi.json.
   Note: The Open API specification URL must be publicly accessible.
6. Review the connector configuration details, and then click Create.

If the connector creation is successful, the newly created connector will be displayed in the Go to the Custom connectors page. However, note that, to connect to your backend, you must create a connection for the newly created connector. For more information, see Create a custom connector connection.

API

The following sample commands show how to create a custom connector by using the Application Integration APIs:

1. Create the connector.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -d '{"customConnectorType":"OPEN_API", \
   "displayName":"CUSTOM_CONNECTOR_NAME", \
   "description": "an open api based custom connector for hrms"}' \
   "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"
   

   Replace the following:

   • CUSTOM_CONNECTOR_NAME: A name for the custom connector.
   • PROJECT_ID: The ID of your Google Cloud project.
   • UNIQUE_IDENTIFIER: A unique identifier for the connector. For example custom-connector-1.
2. Configure the custom connector version.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -d '{"spec_location": "SPECIFICATION_URL",}' \
   "https://connectors.googleapis.comv1/projects/PROJECT_ID/locations/global/customConnectors/openapi-customconnector/customConnectorVersions?custom_connector_version_id=VERSION_NUMBER"
   

Replace the following:

• SPECIFICATION_URL: The Open API specification URL. For example, https://petstore3.swagger.io/api/v3/openapi.json.
• PROJECT_ID: The ID of your Google Cloud project.
• VERSION_NUMBER: A version number for the connector. For example, 2.

Create a custom connector with indirect connectivity

To create a custom connector that connects to your backend through an intermediary endpoint, do the following steps:

Console

1. In the Console, go to the Application Integration > Custom connectors page, and then select or create a Google Cloud project.

   Go to the Custom connectors page

2. Click Create new to open the Create custom connector page.
3. In the Connector details section, set the following fields:
   1. Connector name: Enter a name for the connector.
   2. Display name: Enter a display name for the connector.
   3. Description: Enter a description.
   4. Custom connector type: Select the custom connector type.
   5. Service account: Select a service account that has the required roles.
4. Click Next.
5. In the Connector specification section, enter the URL of your intermediary service's Open API specification in the Specification URL field, and then select the Configure connector destination for backend access option.

   This shows the additional configuration sections in the page.

6. Click Next.
7. In the Connector destination section, set the following fields:
   1. Destination type: Select Host address.
   2. Host: Enter the host name where your intermediary service is running.
   3. Port: Enter the port number of your intermediary service.
8. Click Next.
9. In the Connector authentication section, select the intermediary service's authentication type, and then enter the corresponding details as prompted. This step is to configure the authentication from Application Integration to the intermediary service.

   The authentication configuration from the intermediary service to the backend can't be configured in Application Integration; it's up to the intermediary service on how it wants to authenticate with the backend.

10. Click Next.
11. In the Backend variables section, enter the values that you want to send to your backend through the intermediary service. You must configure the values as key-value paris. To enter a key-value pair, click Add variable, and then set the following fields:
    • Key: Enter the key name.
    • Value type: Select the datatype of the variable.
    • Display name: Enter a display name.
    • Location: Specify how you want the connector to send the variables to the intermediary service. The available options are; Header, Request payload, and Query parameter.
    • Optionally, select Required to specify that the variable is a mandatory variable.
    Note: You will be prompted to enter the values of the configured variables when creating a connection.
12. Click Next.
13. Review the connector configuration details, and then click Create.

If the connector creation is successful, the newly created connector will be displayed in the Go to the Custom connectors page. However, note that, to connect to your backend, you must create a connection for the newly created connector. For more information, see Create a custom connector connection.

API

The following sample commands show how to create a custom connector by using the Application Integration APIs:

1. Create the connector.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json"
   -d '{"customConnectorType":"OPEN_API", \
   "displayName":"CUSTOM_CONNECTOR_NAME", \
   "description": "an open api based custom connector for hrms"}' \
   "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors?custom_connector_id=UNIQUE_IDENTIFIER"
   

   Replace the following:

   • CUSTOM_CONNECTOR_NAME: A name for the custom connector.
   • PROJECT_ID: The ID of your Google Cloud project.
   • UNIQUE_IDENTIFIER: A unique identifier for the connector. For example custom-connector-1.
2. Configure the custom connector version and the authentication.

   curl -X POST \
   -H "authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -d '{"spec_location": "SPECIFICATION_URL", \
   "service_account":"test-sa", \
   "enable_backend_destination_config": true, \
   "auth_config": { \
   "auth_type":"USER_PASSWORD", \
   "auth_key": "basic", \
   "user_password": { \
   "username":"USERNAME", \
   "password": {"secret_version":"projects/PROJECT_ID/secrets/fidelity-secret/versions/SECRET_VERSION_NUMBER"} \
   }}, \
   "backend_variable_templates": [{ \
   "key":"authkey", \
   "value_type":"SECRET", \
   "display_name":"Authorization Key", \
   "required":true, \
   "location_type": "HEADER" \
   }], \
   "destination_configs":[{ \
   "key":"base_url", \
   "destinations": [{ \
   "host":"DESTINATION_HOST_ADDRESS" \
   }]} \
   ]}' \
   "https://connectors.googleapis.com/v1/projects/PROJECT_ID/locations/global/customConnectors/facade-connector/customConnectorVersions?custom_connector_version_id=CONNECTOR_VERSION_NUMBER"
   

Replace the following:

• SPECIFICATION_URL: The Open API specification URL. For example, https://petstore3.swagger.io/api/v3/openapi.json.
• PROJECT_ID: The ID of your Google Cloud project.
• USERNAME: Username for authentication with the intermediary service.
• SECRET_VERSION_NUMBER: The Secret Manager secret version number. For example, 2.
• DESTINATION_HOST_ADDRESS: Host address of the intermediary service. For example, http://www.test.com:80.
• CONNECTOR_VERSION_NUMBER: The custom connector version number. For example, 1.
Note: This sample API call uses Username and Password authentication. Based on your requirements, you can use a different authentication type.

Create a custom connector connection

After creating your custom connector, to connect to your backend, you must create a connection of the custom connector type. The following are the high-level steps to create a new connection:

1. Click Create new to open the Create connection page.
2. In the Location section, select a location for the connection from the Region field.

   For the list of all the supported regions, see Locations.

3. Click Next.
4. In the Connection details section, set the following fields:
   1. Connector: Select your custom connector from the drop down list of available connectors.
   2. Connector version: Select the Connector version from the drop down list of available versions.
   3. In the Connection name field, enter a name for the connection.

      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.
   4. Optionally, enter a Description for the connection.
   5. Optionally, select Enable cloud logging to enable cloud logging.
   6. Service account: Select a service account that has the required roles.
   7. Optionally, configure the Connection node settings:
      • Minimum number of nodes: Enter the minimum number of connection nodes.
      • Maximum number of nodes: Enter the maximum number of connection nodes.

      A node is a unit (or replica) of a connection that processes transactions. More nodes are required to process more transactions for a connection and conversely, fewer nodes are required to process fewer transactions. To understand how the nodes affect your connector pricing, see Pricing for connection nodes. If you don't enter any values, by default the minimum nodes are set to 2 (for better availability) and the maximum nodes are set to 50.

   Note: You can customize the connection node values only if you are a Pay-as-you-go customer.
   8. Optionally, click Add label to add a label to the connection in the form of a key-value pair.
5. Click Next.
6. In the Authentication section, enter the authentication details for your backend.
   • If you connect directly to your backend, Application Integration prompts you to configure the authentication for your backend.
   • If you connect indirectly to your backend through an intermediary service, Application Integration doesn't prompt you to configure authentication details. When creating the connector, you would have already configured the authentication between Application Integration and the intermediary service. Application Integration doesn't require you to configure the authentication between the intermediary service and the backend; it's up to the intermediary service on how it wants to authenticate with the backend.
7. Click Next.
8. Review the connection configuration details, and then click Create.

If the connection creation is successful, it's listed in the All connections page, and the connection becomes available for in Application Integration. You can use the connection in your integration through the Connectors task.

Considerations

Consider the following points when creating a custom connector:

• Application Integration supports only OpenAPI version 3.0 and all it's minor versions.
• The Open API specification isn't validated during custom connector creation. When you create a connection for the custom connector, Application Integration validates the specification, and if it has errors, the connection will be in the Error state.
• Application Integration doesn't differentiate between entities and actions. Hence, both the entities and actions of your backend will be listed as Actions in your custom connector.
• Custom connectors aren't supported in Google Cloud projects that have VPC Service Controls enabled.
• Both the Open API specification endpoint, and the backend endpoint should be publicly accessible. This means that you can't establish private connectivity to your backend.
• Multi-part media type isn't supported in the Open API specification.
• Currently, once you create a custom connector, you can't edit it's details.