ExternalCallout policy

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

policy icon

What

The ExternalCallout policy enables you to send gRPC requests to your gRPC server to implement custom behavior that isn't supported by Apigee policies. In your server's code, you can easily access and modify flow variables within a proxy's flow.

Apigee communicates with a gRPC server through an ExternalCallout policy via an API. Apigee uses the API to send flow variables to the gRPC server. Within your gRPC server, you can read—and depending on the variable, modify— the flow variables listed in the Flow variables reference page, as well as additional variables you specify within the policy's XML.

If you configure the gRPC server with Apigee and include this policy in a proxy, Apigee will handle API requests as follows:

  1. Apigee sends a message containing the flow variables to your gRPC server.
  2. Your gRPC server code executes, accessing and modifying variables as defined in the code. The gRPC server then sends a response containing all the flow variables back to Apigee.
  3. Apigee reads the response from your gRPC server. If any variables are added or modifiable flow variables are modified, they are updated in Apigee.

To learn more about sending gRPC requests, see the following links:

<ExternalCallout>

Defines an ExternalCallout policy.

<ExternalCallout async="true" continueOnError="true" enabled="true" name="EC">

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails.
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

The following table describes the child elements of <ExternalCallout>.

Child Element Required Description
<TimeoutMs> Required The request timeout in milliseconds for gRPC requests.
<GrpcConnection> Required Specifies the name of an existing TargetServer to be the gRPC server to send requests to.
<Configurations> Optional Allows you to configure various aspects of the ExternalCallout policy, including the <Property> and <FlowVariable> elements.

Example

The following example illustrates the ExternalCallout policy.

<ExternalCallout enabled="true" continueOnError="false" name="ExternalCallout-1">
  <DisplayName>External Callout 1</DisplayName>
  <TimeoutMs>5000</TimeoutMs>
  <GrpcConnection>
    <Server name="external-target-server"/>
  </GrpcConnection>
  <Configurations>
    <Property name="with.request.content">true</Property>
    <Property name="with.request.headers">false</Property>
    <Property name="with.response.content">true</Property>
    <Property name="with.response.headers">false</Property>
    <FlowVariable>example1.flow.variable</FlowVariable>
    <FlowVariable>example2.flow.variable</FlowVariable>
  </Configurations>
<ExternalCallout>

The example sends a request to an external gRPC server represented by the TargetServer named external-target-server, with the following configurations:

  • <Property>: Include request and response content, but not the request and response headers, in the request sent to the gRPC server.
  • <FlowVariable>: Include additional flow variables example1.flow.variable and example2.flow.variable, specified by the FlowVariable elements, in the request sent to the gRPC server.

Child element reference

The following sections describe the child elements of ExternalCallout.

<TimeoutMs>

The request timeout in milliseconds for gRPC requests. <TimeoutMs> must be a positive number.

<GrpcConnection>

The <GrpcConnection> element sets the gRPC server to be an existing TargetServer, specified by the name attribute. See the TargetServer resource reference page.

Note: The protocol for the TargetServer must be GRPC.

For example, the following code

<GrpcConnection>
  <Server name="external-target-server"/>
</GrpcConnection>

specifies the gRPC server to be an existing TargetServer named external-target-server.

The following table describes the child elements of <GrpcConnection>.

Child Element Required? Description
<Server> Required Specifies the gRPC server.

Server

Specifies the gRPC server.

The following table describes the attributes of the <Server> element.

Attribute Description Default Presence Type
name

The name of an existing TargetServer to be the gRPC server to send requests to.

N/A Required String

<Configurations>

The <Configurations> element allows you to configure various aspects of the ExternalCallout policy, including <Property> and <FlowVariable>.

The following table describes the child elements of <Configurations>.

Child Element Required? Description
<Property> Required

Specifies whether request/response headers and/or content will be sent to the server. Possible values are true or false. The default is false.

<FlowVariable> Required

Specifies what additional flow variables should be sent to the server.

<Property>

The <Property> element specifies whether request/response headers and/or content will be sent to the server. Possible values are true (the item will be sent) or false (the item won't be sent). The default value is false.

The following table describes the attributes of the <Property> element.

Attribute Description Default Presence Type
name

Specifies what content will be sent to the server. Possible values for name are:

  • with.request.content
  • with.request.headers
  • with.response.content
  • with.response.headers
N/A Required String

<FlowVariable>

The <FlowVariable> element specifies what additional flow variables will be sent to the server. The value of <FlowVariable> is a prefix of a variable, rather than the full variable name. For example , if the element is a.b.c, the value of a variable named a.b.c will be sent to the server. Similarly, the value of a variable named a.b.c.my-variable will be sent to the server. But the value of a variable named a.x.another-variable will not be sent, because it does not have the prefix a.b.c. Here are some examples

<Configurations>
  <FlowVariable>a.b.c</FlowVariable>
  <FlowVariable>d.e.f</FlowVariable>
</Configurations>

Error Reference

Runtime errors

The table below describes runtime errors, which can occur when the policy executes.

Fault code HTTP Status Cause
GrpcTlsInitFailed 500

This error will occur if there are any issues with initializing TLS with the gRPC server (such as Keystore or truststore issues).

steps.externalcallout.[error_code] 500

[error_code] is determined by the Fault message's errorCode field. The fault string of the error will be the fault message's faultstring field.

steps.externalcallout.ExecutionError 500

This error will occur if any other exception occurs during the execution of this policy. The underlying exception will be exposed in the faultstring. If there was an issue with the credentials to the gRPC server, the error will look something like this:

{
    "fault": {
        "faultstring": "Encountered the following exception while sending the gRPC request or
         processing the response: [io.grpc.StatusRuntimeException: UNAVAILABLE: Credentials failed
         to obtain metadata].",
        "detail": {
            "errorcode": "steps.externalcallout.ExecutionError"
        }
    }
}

You can look at the logs of the MP for further debugging pointers.

Miscellaneous errors

The table below describes miscellaneous errors. See the cause for more details.

Fault code Cause
ReferencesExistToGrpcServer

This error will occur if a user tries to delete a gRPC target server, but the server is still being used by other policies.

Faults

The fault variables in the following table are set for all policies by default. See Variables specific to policy errors.

Variables Where Examples
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name matches "ExecutionError".
externalcallout.[policy_name].failed policy_name is the user-specified name of the policy that threw the fault. externalcallout.ExternalCallout-1.failed = true

Related topics