ExtensionCallout policy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Use the ExtensionCallout policy to incorporate an extension into an API proxy.

An extension provides access to a specific resource external to Apigee Edge. The resource could be Google Cloud Platform services such as Cloud Storage or Cloud Speech-to-Text. But the resource could be any external resource accessible over HTTP or HTTPS.

For an overview of extensions, see What are extensions? For an introductory tutorial, see Tutorial: Adding and using an extension.

Before accessing an extension from the ExtensionCallout policy, you must add, configure, and deploy the extension from an extension package that is already installed into your Apigee Edge organization.

Samples

Shown below is an example policy for use with the Cloud Logging extension:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

See Tutorial: Using extensions for a complete tutorial using the Cloud Logging extension.

For examples for all available extensions, see Extensions reference overview.

About the ExtensionCallout policy

Use the ExtensionCallout policy when you want to use a configured extension to access an external resource from within an API proxy.

Before you use this policy, you'll need:

• A few details about the external resource you want to access from this policy. These details will be specific to the resource. For example, if the policy will access your Cloud Firestore database, you'll need to know the collection and document name you want to create or access. You'll typically use resource-specific information in configuring this policy's request and response handling.
• An extension added, configured, and deployed to the environment where your API proxy will be deployed. In other words, if you're going to use this policy to access a particular Google Cloud service, then a deployed extension for that service must exist in your environment. The configuration details typically include required information for narrowing access to the resource, such as a project ID or account name.

Using the ExtensionCallout policy in a PostClientFlow

You can invoke the ExtensionCallout policy from the PostClientFlow of an API proxy. The PostClientFlow executes after the response is sent to the requesting client, which ensures that all metrics are available for logging. For details on using PostClientFlow, see API proxy configuration reference.

If you want to use the ExtensionCallout policy to call the Google Cloud Logging extension from a PostClientFlow, ensure that the features.allowExtensionsInPostClientFlow flag is set to true in your organization.

• If you are an Apigee Edge for Public Cloud customer, the features.allowExtensionsInPostClientFlow flag is set to true by default.

• If you are an Apigee Edge for Private Cloud customer, use the Update organization properties API to set the features.allowExtensionsInPostClientFlow flag to true.

All restrictions on calling the MessageLogging policy from the PostClientFlow also apply to the ExtensionCallout policy. See Usage notes for more.

Element reference

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

<ConnectorCallout> attributes

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

<Action> element

The extension-exposed action that the policy should invoke.

<Action>action-exposed-by-extension</Action>

Each extension exposes its own set of actions that provide access to functionality of the resource the extension represents. You can think of an action as a function you call with this policy, using the contents of the <Input> element to specify the function's arguments. The action's response is stored in the variable you specify with the <Output> element.

For a list of the extension's functions, see the reference for the extension you're calling from this policy.

<Connector> element

The name of the configured extension to use. This is the environment-scoped name given the extension when it was configured for deployment to an environment.

<Connector>name-of-configured-extension</Connector>

An extension has configuration values that might differ from another deployed extension based on the same extension package. These configuration values can represent important differences in runtime functionality between extensions configured from the same package, so be sure to specify the correct extension to invoke.

<Input> element

JSON containing the request body to send to the extension.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

This is essentially an argument to the action you specify with the <Action> element. The <Input> element's value will vary depending on the extension and action you're invoking. See the extension package documentation for details about each action's properties.

Note that while many <Input> element values will function correctly without being enclosed as a <![CDATA[]]> section, the rules of JSON allow for values that will not parse as XML. As a best practice, enclose the JSON as a CDATA section to avoid runtime parse errors.

The <Input> element's value is well-formed JSON whose properties specify values to send to the extension action to invoke. For example, the Google Cloud Logging Extension extension's log action takes values specifying the log to write to (logName), metadata to include with the entry (metadata), and the log message (data). Here's an example:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

Using flow variables in <Input> JSON

The content of <Input> is treated as a message template. This means that a variable name wrapped in curly braces will be replaced at runtime with the value of the referenced variable.

For example, you could rewrite the preceding <Input> block to use the client.ip flow variable to get the IP address of the client calling the API proxy:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

If you intend a property value in the JSON to be enclosed in quotation marks at runtime, be sure to use quotation marks in your JSON code. This is true even when you specify a flow variable as a JSON property value to be resolved at runtime.

The following <Input> example includes two flow variable references:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

At runtime, JSON property values will resolve as follows:

• logName property value -- the string literal example-log.
• metadata property value -- the my.log.entry.metadata flow variable value without enclosing quotation marks. This can be useful if the variable's value is itself JSON representing an object.
• message property value -- the client.ip flow variable value with enclosing quotation marks.

<Output> element

Name of a variable that stores the extension action's response.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

or

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

When the response is received, the response value is placed into the variable you specify here, where you can access it from other API proxy code.

Extension response objects are in JSON format. There are two options for how the policy handles the JSON:

• Parsed (default): The policy parses the JSON object and automatically generates variables with the JSON data. For example, if the JSON contains "messageId" : 12345; and you name your output variable extensionOutput, you can access that message ID in other policies using the variable {extensionOutput.messageId}.
• Unparsed: The output variable contains the raw, unparsed JSON response from the extension. (If you wanted to, you could still parse the response value in a separate step using the JavaScript policy.)

<Output> Attributes

Flow variables

None.

Error codes

Errors returned from Apigee Edge policies follow a consistent format as described in the Policy error reference.

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.