0
# Function Invocation
1

2
Direct function invocation capabilities supporting synchronous, asynchronous, and dry-run execution modes with full payload control and response handling.
3

4
## Capabilities
5

6
### Standard Function Invocation
7

8
Primary method for invoking Lambda functions with configurable execution type.
9

10
```java { .api }
11
/**
12
 * Invokes Lambda function synchronously or asynchronously
13
 * @param request Invocation parameters including function name, payload, and type
14
 * @return InvokeResult containing response payload, status, and logs
15
 * @throws ServiceException if service encounters an error
16
 * @throws ResourceNotFoundException if function doesn't exist
17
 * @throws InvalidParameterValueException if parameters are invalid
18
 * @throws TooManyRequestsException if concurrent executions exceed limits
19
 * @throws EC2UnexpectedException if VPC configuration causes issues
20
 * @throws EC2ThrottledException if VPC operations are throttled
21
 * @throws EC2AccessDeniedException if VPC access is denied
22
 * @throws ENILimitReachedException if VPC ENI limit is reached
23
 * @throws SubnetIPAddressLimitReachedException if VPC subnet IP limit reached
24
 * @throws InvalidSubnetIDException if VPC subnet ID is invalid
25
 * @throws InvalidSecurityGroupIDException if VPC security group ID is invalid
26
 * @throws InvalidZipFileException if deployment package is invalid
27
 * @throws KMSDisabledException if KMS key is disabled
28
 * @throws KMSInvalidStateException if KMS key is in invalid state
29
 * @throws KMSAccessDeniedException if KMS access is denied
30
 * @throws KMSNotFoundException if KMS key not found
31
 * @throws InvalidRuntimeException if runtime is invalid
32
 * @throws ResourceConflictException if function is being modified
33
 * @throws ResourceNotReadyException if function is not ready
34
 * @throws SnapStartException if SnapStart configuration causes errors
35
 * @throws SnapStartTimeoutException if SnapStart times out
36
 * @throws SnapStartNotReadyException if SnapStart is not ready
37
 * @throws RecursiveInvocationException if function invokes itself recursively
38
 */
39
InvokeResult invoke(InvokeRequest request);
40

41
public class InvokeRequest {
42
    /** Function name, ARN, or qualified ARN (required) */
43
    private String functionName;
44
    /** Invocation type (optional, default: RequestResponse) */
45
    private InvocationType invocationType;
46
    /** Log type for response (optional, default: None) */
47
    private LogType logType;
48
    /** Client context for mobile apps (optional) */
49
    private String clientContext;
50
    /** JSON payload for function (optional) */
51
    private ByteBuffer payload;
52
    /** Function version or alias (optional, default: $LATEST) */
53
    private String qualifier;
54
    
55
    public InvokeRequest withFunctionName(String functionName) { ... }
56
    public InvokeRequest withInvocationType(InvocationType invocationType) { ... }
57
    public InvokeRequest withLogType(LogType logType) { ... }
58
    public InvokeRequest withClientContext(String clientContext) { ... }
59
    public InvokeRequest withPayload(ByteBuffer payload) { ... }
60
    public InvokeRequest withPayload(String payload) { ... }
61
    public InvokeRequest withQualifier(String qualifier) { ... }
62
}
63

64
public class InvokeResult {
65
    /** HTTP status code (200 for success) */
66
    private Integer statusCode;
67
    /** Function error type (null for success) */
68
    private String functionError;
69
    /** Base64-encoded execution logs (if LogType.Tail) */
70
    private String logResult;
71
    /** Response payload from function */
72
    private ByteBuffer payload;
73
    /** Function version executed */
74
    private String executedVersion;
75
    
76
    /** Get payload as string */
77
    public String getPayloadAsString() {
78
        return payload != null ? new String(payload.array()) : null;
79
    }
80
    
81
    /** Check if invocation was successful */
82
    public boolean isSuccessful() {
83
        return statusCode != null && statusCode == 200 && functionError == null;
84
    }
85
    
86
    // Standard getters
87
}
88

89
/** Invocation type enumeration */
90
public enum InvocationType {
91
    /** Synchronous invocation (default) - waits for response */
92
    RequestResponse,
93
    /** Asynchronous invocation - returns immediately */
94
    Event,
95
    /** Validation only - doesn't execute function */
96
    DryRun
97
}
98

99
/** Log type enumeration */
100
public enum LogType {
101
    /** No logs in response (default) */
102
    None,
103
    /** Include last 4KB of logs in response (base64 encoded) */
104
    Tail
105
}
106
```
107

108
### Legacy Asynchronous Invocation (Deprecated)
109

110
Legacy method for asynchronous function invocation.
111

112
```java { .api }
113
/**
114
 * @deprecated Use invoke() with InvocationType.Event instead
115
 * Legacy asynchronous function invocation
116
 * @param request Async invocation parameters
117
 * @return InvokeAsyncResult with basic status information
118
 * @throws ServiceException if service encounters an error
119
 * @throws ResourceNotFoundException if function doesn't exist
120
 * @throws InvalidRequestContentException if request content is invalid
121
 */
122
@Deprecated
123
InvokeAsyncResult invokeAsync(InvokeAsyncRequest request);
124

125
@Deprecated
126
public class InvokeAsyncRequest {
127
    /** Function name (required) */
128
    private String functionName;
129
    /** JSON payload (required) */
130
    private InputStream invokeArgs;
131
    
132
    public InvokeAsyncRequest withFunctionName(String functionName) { ... }
133
    public InvokeAsyncRequest withInvokeArgs(InputStream invokeArgs) { ... }
134
}
135

136
@Deprecated
137
public class InvokeAsyncResult {
138
    /** HTTP status code */
139
    private Integer status;
140
    
141
    public Integer getStatus() { return status; }
142
}
143
```
144

145
**Usage Examples:**
146

147
```java
148
import com.amazonaws.services.lambda.*;
149
import com.amazonaws.services.lambda.model.*;
150
import java.nio.ByteBuffer;
151
import java.nio.charset.StandardCharsets;
152
import com.fasterxml.jackson.databind.ObjectMapper;
153

154
// Create client
155
AWSLambda lambdaClient = AWSLambdaClientBuilder.defaultClient();
156
ObjectMapper objectMapper = new ObjectMapper();
157

158
// Synchronous invocation with JSON payload
159
Map<String, Object> payload = new HashMap<>();
160
payload.put("name", "John");
161
payload.put("age", 30);
162
String payloadJson = objectMapper.writeValueAsString(payload);
163

164
InvokeRequest request = new InvokeRequest()
165
    .withFunctionName("my-function")
166
    .withInvocationType(InvocationType.RequestResponse)
167
    .withLogType(LogType.Tail)
168
    .withPayload(payloadJson);
169

170
InvokeResult result = lambdaClient.invoke(request);
171

172
if (result.isSuccessful()) {
173
    String response = result.getPayloadAsString();
174
    System.out.println("Function response: " + response);
175
    
176
    // Parse logs if requested
177
    if (result.getLogResult() != null) {
178
        String logs = new String(Base64.getDecoder().decode(result.getLogResult()));
179
        System.out.println("Function logs: " + logs);
180
    }
181
} else {
182
    System.err.println("Function error: " + result.getFunctionError());
183
    System.err.println("Status code: " + result.getStatusCode());
184
}
185

186
// Asynchronous invocation (fire and forget)
187
InvokeRequest asyncRequest = new InvokeRequest()
188
    .withFunctionName("my-async-function")
189
    .withInvocationType(InvocationType.Event)
190
    .withPayload("{\"message\": \"Hello, async world!\"}");
191

192
InvokeResult asyncResult = lambdaClient.invoke(asyncRequest);
193
System.out.println("Async invocation status: " + asyncResult.getStatusCode());
194

195
// Dry run validation
196
InvokeRequest dryRunRequest = new InvokeRequest()
197
    .withFunctionName("my-function")
198
    .withInvocationType(InvocationType.DryRun)
199
    .withPayload("{\"test\": true}");
200

201
InvokeResult dryRunResult = lambdaClient.invoke(dryRunRequest);
202
if (dryRunResult.getStatusCode() == 204) {
203
    System.out.println("Function validation successful");
204
} else {
205
    System.out.println("Function validation failed");
206
}
207

208
// Invoke specific version or alias
209
InvokeRequest versionRequest = new InvokeRequest()
210
    .withFunctionName("my-function")
211
    .withQualifier("v1") // or alias like "PROD"
212
    .withPayload("{\"version\": \"specific\"}");
213

214
InvokeResult versionResult = lambdaClient.invoke(versionRequest);
215
System.out.println("Executed version: " + versionResult.getExecutedVersion());
216

217
// Error handling example
218
try {
219
    InvokeRequest errorRequest = new InvokeRequest()
220
        .withFunctionName("non-existent-function")
221
        .withPayload("{}");
222
    
223
    InvokeResult errorResult = lambdaClient.invoke(errorRequest);
224
} catch (ResourceNotFoundException e) {
225
    System.err.println("Function not found: " + e.getMessage());
226
} catch (TooManyRequestsException e) {
227
    System.err.println("Too many concurrent executions: " + e.getMessage());
228
} catch (Exception e) {
229
    System.err.println("Invocation failed: " + e.getMessage());
230
}
231

232
// Working with binary payloads
233
byte[] binaryData = "Binary payload content".getBytes(StandardCharsets.UTF_8);
234
InvokeRequest binaryRequest = new InvokeRequest()
235
    .withFunctionName("binary-function")
236
    .withPayload(ByteBuffer.wrap(binaryData));
237

238
InvokeResult binaryResult = lambdaClient.invoke(binaryRequest);
239
byte[] responseBytes = binaryResult.getPayload().array();
240

241
// Asynchronous client example
242
AWSLambdaAsync asyncClient = AWSLambdaAsyncClientBuilder.defaultClient();
243

244
Future<InvokeResult> futureResult = asyncClient.invokeAsync(request, 
245
    new AsyncHandler<InvokeRequest, InvokeResult>() {
246
        @Override
247
        public void onError(Exception exception) {
248
            System.err.println("Async invocation failed: " + exception.getMessage());
249
        }
250
        
251
        @Override
252
        public void onSuccess(InvokeRequest request, InvokeResult result) {
253
            System.out.println("Async invocation completed: " + result.getPayloadAsString());
254
        }
255
    });
256

257
// Wait for async result if needed
258
try {
259
    InvokeResult asyncResponse = futureResult.get(30, TimeUnit.SECONDS);
260
    System.out.println("Async result: " + asyncResponse.getPayloadAsString());
261
} catch (TimeoutException e) {
262
    System.err.println("Async invocation timed out");
263
    futureResult.cancel(true);
264
}
265
```