Getting started with Application Integration and Apigee proxy Integration targets

This tutorial shows you how to use the Apigee proxy wizard to create a proxy with an Integration target. The proxy utilizes an API trigger reference from an existing integration to initiate the sequence of steps in the integration.

The steps below describe how to configure the Integration target proxy to run a successful integration when the proxy is called.

Before you begin

Confirm your Apigee login credentials and organization details. This information is required to access the Application Integration feature and proxy wizard within the Apigee UI.
Create and publish an integration with an API Trigger and at least one task.
- If you have not yet created an integration that uses an API Trigger, follow the steps in Retrieve API payload and send an email.
- Note the name of the integration you create, or the existing integration that you would like to use, as this is used in a later step.
Create a Google service account in the same Google Cloud project where your Apigee organization was created, and do the following:
- Assign the Application Integration Invoker role (roles/integrations.applicationIntegrationInvokerRole) to the service account. For information about the predefined Application Integration roles, see Predefined IAM roles.
- Allow your user account (principal) to attach service accounts to resources with the iam.serviceAccounts.actAs permission. For information on service account permissions, see Roles for service account authentication .
You must provide this service account when you deploy the API proxy.
If you want to use Application Integrations without any limitations, you can pay for the integrations. Application Integration is available as an add-on service for your subscription. If you have already purchased the Application Integration entitlement, and want to enable the entitlement to your Google Cloud project or Apigee organization, contact Apigee support. However, if you want to purchase the Application Integration entitlement, contact Apigee sales. After Application Integration has been enabled for you, perform the following tasks:
1. Enable the following APIs:
  - Apigee API (apigee.googleapis.com)
  - Application Integration API (integrations.googleapis.com)
  - Secret Manager API (secretmanager.googleapis.com)
  - Connectors API (connectors.googleapis.com)
  For information on how to enable the APIs, see Enabling services.
2. Enable the Integration and the Connectors add-ons for your Apigee organization.
  - If you are creating a new organization to use for Integration, run the following command:
```
curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json" -d '{"name":"${ORG_ID}", "analyticsRegion":"us-west1", "authorized_network":"${NETWORK_ID}", "runtimeType":"CLOUD", "runtimeDatabaseEncryptionKeyName":"${ENCRYPTION_KEY_NAME}", "addonsConfig": {"integrationConfig": {"enabled": true}, "connectorsPlatformConfig":{"enabled":true}}}' "https://apigee.googleapis.com/v1/organizations?parent=projects/${PROJECT_ID}"
```
  - If you are using an existing organization, run the following command:
```
curl -H "Authorization: Bearer $TOKEN" -H "content-type:application/json" "https://apigee.googleapis.com/v1/organizations/${ORG_ID}:setAddons" -XPOST -d '{"addonsConfig":{"integrationConfig":{"enabled":true},"connectorsPlatformConfig":{"enabled":true}}}'
```
3. Verify if the add-ons are successfully enabled using the following command:
```
curl -H "Authorization: Bearer $TOKEN"  -H "content-type:application/json" "https://apigee.googleapis.com/v1/organizations/${ORG_ID}"
```
  Running the command, should display a message similar to the following:
```
{
  "name": "Test....",
  "createdAt": "1615483867669",
  "lastModifiedAt": "1615483873468",
  …...
  "addonsConfig": {
    "integrationConfig": {
      "enabled": true,
    "connectorsPlatformConfig": {
      "enabled": true
    }
  }
  }
```
  Note:
  - 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.
  - Disabling an add-on, deletes all configurations of the add-on (feature). For example, if you disable the Integrations add-on, all integrations are deleted.
4. Assign the following IAM roles to your default Apigee service account(service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com):
  - Application Integration Invoker (roles/integrations.applicationIntegrationInvokerRole)
  For information about granting additional roles or permissions to a service account, see Granting, changing, and revoking access.

Create an Application Integration target proxy

Do the following to create an Integration target proxy in the Apigee UI:

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 API Proxies in the main view.
Alternatively, you can select Develop > API Proxies in the left navigation menu.
From the Environment drop-down list, select the environment in which you want to create a new API proxy.
Click Create New.
Select Integration target from the display of proxy types.
The Create Proxy wizard starts.
In the Proxy details configuration page, provide the following details:
- Name: Enter a name for the proxy.
  Proxy names can contain alphanumeric characters, dashes, and underscores.
- Base Path: This is autopopulated based on the proxy name.
  The Base Path is part of the URL used to make requests to your API. Apigee uses the URL to match and route incoming requests to the proper API proxy.
- Description: (Optional) Enter a brief description of the proxy.
  For example, Proxy test for Application Integration.
- Integration region: Select the region of the integration from the drop-down list.
- Integration target: Select the name of the integration target from the drop-down list. Note that the integration target list is populated based on the integration region selected.
- Trigger: Select the API trigger associated with the integration from the drop-down list.
- Endpoint type: Select Sync.
Click Next.
In the Common policies configuration page, leave the default selections and click Next.
In the Summary page, click Create.
An Integration target proxy is created successfully.

Deploy the proxy

Perform the following steps to deploy the newly created proxy:

In the Apigee UI, select Develop > API Proxies.
The UI displays a list of API proxies and their deployment status.
From the Environment drop-down list, select the environment to which you want to deploy the API proxy.
Click the recently created proxy that you want to deploy. The UI displays the Overview page by default.
To deploy your changes, first click Deploy to display the Deploy dialog.
Enter the following:
- Revision: The revision number of the proxy you want to deploy.
- Environment: The environment where you want to deploy the proxy.
- Service account: The created service account for the proxy.
Click Deploy.

The UI begins the process of deploying the selected revision. It can take up to a minute for the proxy deployment to complete.

When the proxy is deployed, the Status column in the Deployments section diplays a green icon to show that revision 1 of the proxy is deployed.

Note: There is no explicit Authentication element in the Set Integration Request policy definition of the proxy. Apigee adds an authentication token to the request automatically.

For the Set Integration Request policy to successfully authenticate, you must deploy your Integration target with a service account that has the required IAM roles to run an integration. For more details on deploying an API proxy, see Deploy on Apigee.

Test the Integration target proxy

Run the following command from the terminal window to invoke the proxy and trigger the integration:

curl -v https://YOUR_ENV_GROUP_HOSTNAME/PROXY_NAME

where YOUR_ENV_GROUP_HOSTNAME is the hostname for an environment group that contains the environment in which your proxy is deployed.

For example:

curl -v https://my-org-prod.hybrid.e2e.apigeeks.net/my-proxy

To confirm that the integration was triggered by invoking the proxy:

Open the Apigee UI.
Click Develop > Integrations.
Search for or select the name of the integration created in the steps above and click the integration name.
Click Logs.
Verify that an execution log exists for the triggered integration. To see the log details, click the row to expand the execution details.

Update the proxy request payload (Optional)

Use the following steps to update the proxy request payload:

In the Apigee UI, select Develop > API Proxies in the left navigation menu.
Click the recently created proxy.
By default, the UI displays the Overview tab for that proxy in the Proxy Editor.
Click the Develop tab.
In the Navigator pane, select Set Integration Request under the Policies heading.
Uncomment the <Parameters> block, and enter your parameter details.
To specify individual parameters, use the <Parameter> element. To specify parameter arrays, use the <ParameterArray> element.

Note: The Parameters block is left commented in this tutorial for simplicity only. Application Integration supports a number of parameters that can be passed as part of the Set Integration Request policy. For more information and examples, see SetIntegrationRequest policy.
Click Save.

What's next

Explore the Integration designer layout and understand the various integration concepts described in All concepts.