See the supported connectors for Application Integration.
Create a custom connector
This page describes how to create a custom connector. To understand what is a custom connector, see Custom connectors.
To establish connectivity to your backend by using a custom connector, you need to do the following tasks:
- 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.
- 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:
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 with direct connectivity
To create a custom connector with direct connectivity to your backend's endpoint, do the following steps:
Console
- In the Console, go to the Application Integration > Custom connectors page, and then select or create a Google Cloud project.
- Click Create new to open the Create custom connector page.
- In the Connector details section, set the following fields:
- Connector name: Enter a name for the connector.
- Display name: Enter a display name for the connector.
- Description: Enter a description.
- Service account: Select a service account that has the required roles.
- Logo: Upload the image to a Cloud Storage bucket to use it as the connector logo.
- Click Next.
- In the Connector specification section, set the following fields:
- Custom connector type: Select the custom connector type.
- Connector specification: Either enter the public URL of your Open API specification or upload your specification file to a Cloud Storage bucket.
- 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, and if it's a new connector, a first version of the connector is also created. You can view the version details in the Version tab of the Custom Connector details page. For more information, see .
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:
- 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 examplecustom-connector-1
.
- 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"
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
.
Replace the following:
Create with indirect connectivity
To create a custom connector that connects to your backend through an intermediary endpoint, do the following steps:
Console
- In the Console, go to the Application Integration > Custom connectors page, and then select or create a Google Cloud project.
- Click Create new to open the Create custom connector page.
- In the Connector details section, set the following fields:
- Connector name: Enter a name for the connector.
- Display name: Enter a display name for the connector.
- Description: Enter a description.
- Configure connector destination for backend access: Enable this option. This shows the additional configuration sections in the page.
- Service account: Select a service account that has the required roles.
- Logo: Upload the image to a Cloud Storage bucket to use it as the connector logo.
- Click Next.
- In the Connector specification section, set the following fields:
- Custom connector type: Select the custom connector type.
- Connector specification: Either enter the public URL of your Open API specification or upload your specification file to a Cloud Storage bucket.
- Click Next.
- In the Connector destination section, set the following fields:
- Destination type: Select Host address.
- Host: Enter the host name where your intermediary service is running.
- Port: Enter the port number of your intermediary service.
- Click Next.
- 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.
- Click Next.
- 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
, andQuery parameter
. - Optionally, select
Required
to specify that the variable is a mandatory variable.
- Click Next.
- Review the connector configuration details, and then click Create.
If the connector creation is successful, the newly created connector will be displayed in the Custom connectors page, and if it's a new connector, a first version of the connector is also created. You can view the version details in the Version tab of the Custom Connector details page. For information on creating and editing a custom connector version, see Manage custom connector versions.
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:
- 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 examplecustom-connector-1
.
- 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"
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
.
Replace the following:
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:
- Click Create new to open the Create connection page.
- In the Location section, select a location for the connection from the Region field.
For the list of all the supported regions, see Locations.
- Click Next.
- In the Connection details section, set the following fields:
- Connector: Select your custom connector 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.
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.
- Optionally, select Enable cloud logging to enable cloud logging.
- Service account: Select a service account that has the required roles.
- 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.
- Optionally, click Add label to add a label to the connection in the form of a key-value pair.
- Click Next.
- 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.
- Click Next.
- 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.
- You can't edit the version details of a custom connector.
Quotas and limits
For information about quotas and limits, see Quotas and limits.
What's next
- Learn about all tasks and triggers.
- Learn how to test and publish an integration.
- Learn about error handling.
- Learn about integration execution logs.