0
# Cloud Platform Types
1

2
Cloud-specific types for audit logging, location services, policy violations, and platform integration. These types are essential for Google Cloud Platform services and enterprise audit requirements.
3

4
## Audit Logging
5

6
### AuditLog
7

8
Cloud audit log entry containing comprehensive information about API calls and resource access.
9

10
```java { .api }
11
class AuditLog {
12
  String getServiceName();              // Service that processed the request
13
  String getMethodName();               // Method that was called
14
  String getResourceName();             // Resource that was accessed
15
  String getResourceLocation();         // Location of the resource
16
  String getResourceOriginalState();    // Resource state before operation
17
  AuthenticationInfo getAuthenticationInfo();
18
  repeated AuthorizationInfo getAuthorizationInfoList();
19
  RequestMetadata getRequestMetadata();
20
  Struct getRequest();                  // Request message
21
  Struct getResponse();                 // Response message
22
  Status getStatus();                   // Operation status
23
  int getNumResponseItems();            // Number of items in response
24
  repeated ServiceAccountDelegationInfo getServiceAccountDelegationInfoList();
25
  
26
  static AuditLog.Builder newBuilder();
27
}
28
```
29

30
### AuthenticationInfo
31

32
Authentication details for the principal making the request.
33

34
```java { .api }
35
class AuthenticationInfo {
36
  String getPrincipalEmail();           // Email of authenticated user
37
  String getAuthoritySelector();        // Authority that authenticated
38
  Struct getThirdPartyPrincipal();     // Third-party identity provider info
39
  String getServiceAccountKeyName();    // Service account key used
40
  repeated ServiceAccountDelegationInfo getServiceAccountDelegationInfoList();
41
  String getPrincipalSubject();         // Subject from authentication token
42
  
43
  static AuthenticationInfo.Builder newBuilder();
44
}
45
```
46

47
### AuthorizationInfo
48

49
Authorization details for each permission checked.
50

51
```java { .api }
52
class AuthorizationInfo {
53
  String getResource();                 // Resource being accessed
54
  String getPermission();               // Permission being checked
55
  boolean getGranted();                 // Whether permission was granted
56
  AttributeContext getResourceAttributes(); // Resource attributes
57
  
58
  static AuthorizationInfo.Builder newBuilder();
59
}
60
```
61

62
### RequestMetadata
63

64
Metadata about the request itself.
65

66
```java { .api }
67
class RequestMetadata {
68
  String getCallerIp();                 // IP address of caller
69
  String getCallerSuppliedUserAgent();  // User agent string
70
  String getCallerNetwork();            // Network caller is on
71
  Struct getDestinationAttributes();    // Destination service attributes
72
  repeated AttributeContext.Request getRequestAttributesList();
73
  
74
  static RequestMetadata.Builder newBuilder();
75
}
76
```
77

78
### ServiceAccountDelegationInfo
79

80
Information about service account delegation.
81

82
```java { .api }
83
class ServiceAccountDelegationInfo {
84
  String getFirstPartyPrincipal();      // First party principal
85
  Struct getThirdPartyPrincipal();      // Third party principal
86
  
87
  static ServiceAccountDelegationInfo.Builder newBuilder();
88
}
89
```
90

91
## Location Services
92

93
### Location
94

95
Represents a Google Cloud resource location.
96

97
```java { .api }
98
class Location {
99
  String getName();                     // Full resource name
100
  String getLocationId();               // Location identifier (e.g., "us-central1")
101
  String getDisplayName();              // Human-readable name
102
  Struct getLabels();                   // Labels associated with location
103
  Any getMetadata();                    // Location-specific metadata
104
  
105
  static Location.Builder newBuilder();
106
}
107
```
108

109
### ListLocationsRequest
110

111
Request to list available locations.
112

113
```java { .api }
114
class ListLocationsRequest {
115
  String getName();                     // Parent resource name
116
  String getFilter();                   // Optional filter expression
117
  int getPageSize();                    // Maximum locations to return
118
  String getPageToken();                // Pagination token
119
  
120
  static ListLocationsRequest.Builder newBuilder();
121
}
122
```
123

124
### ListLocationsResponse
125

126
Response containing available locations.
127

128
```java { .api }
129
class ListLocationsResponse {
130
  repeated Location getLocationsList();
131
  String getNextPageToken();            // Token for next page
132
  
133
  static ListLocationsResponse.Builder newBuilder();
134
  int getLocationsCount();
135
  Location getLocations(int index);
136
}
137
```
138

139
### GetLocationRequest
140

141
Request to get information about a specific location.
142

143
```java { .api }
144
class GetLocationRequest {
145
  String getName();                     // Location resource name
146
  
147
  static GetLocationRequest.Builder newBuilder();
148
}
149
```
150

151
## Policy and Violations
152

153
### PolicyViolationInfo
154

155
Information about policy violations.
156

157
```java { .api }
158
class PolicyViolationInfo {
159
  OrgPolicyViolationInfo getOrgPolicyViolationInfo();
160
  
161
  static PolicyViolationInfo.Builder newBuilder();
162
  boolean hasOrgPolicyViolationInfo();
163
}
164
```
165

166
### OrgPolicyViolationInfo
167

168
Specific information about organization policy violations.
169

170
```java { .api }
171
class OrgPolicyViolationInfo {
172
  Struct getPayload();                  // Violation details
173
  repeated String getResourceTagsList(); // Resource tags involved
174
  String getResourceType();             // Type of resource
175
  repeated ViolationInfo getViolationInfoList();
176
  
177
  static OrgPolicyViolationInfo.Builder newBuilder();
178
}
179
```
180

181
### ViolationInfo
182

183
General violation information.
184

185
```java { .api }
186
class ViolationInfo {
187
  String getConstraint();               // Constraint that was violated
188
  String getErrorMessage();             // Error message
189
  CheckedValue getCheckedValue();       // Value that was checked
190
  PolicyType getPolicyType();           // Type of policy
191
  
192
  static ViolationInfo.Builder newBuilder();
193
}
194

195
enum PolicyType {
196
  POLICY_TYPE_UNSPECIFIED(0),
197
  BOOLEAN_POLICY(1),
198
  LIST_POLICY(2),
199
  RESTORE_POLICY(3);
200
  
201
  int getNumber();
202
  static PolicyType forNumber(int value);
203
}
204
```
205

206
## Extended Operations
207

208
### ExtendedOperation
209

210
Extended operation information for cloud operations.
211

212
```java { .api }
213
class ExtendedOperation {
214
  UInt64Value getId();                  // Operation ID
215
  String getName();                     // Operation name
216
  Status getStatus();                   // Current status
217
  String getStatusMessage();            // Status message
218
  String getUser();                     // User who initiated
219
  UInt64Value getProgress();            // Progress percentage
220
  Timestamp getInsertTime();            // When operation started
221
  Timestamp getStartTime();             // When execution began
222
  Timestamp getEndTime();               // When operation completed
223
  repeated ExtendedOperation.Error getErrorsList();
224
  repeated ExtendedOperation.Warning getWarningsList();
225
  UInt64Value getHttpErrorStatusCode(); // HTTP status code
226
  String getHttpErrorMessage();         // HTTP error message
227
  String getSelfLink();                 // Link to operation resource
228
  String getRegion();                   // Region where operation runs
229
  String getDescription();              // Operation description
230
  String getOperationType();            // Type of operation
231
  String getTargetLink();               // Link to target resource
232
  UInt64Value getTargetId();           // Target resource ID
233
  String getClientOperationId();        // Client-specified operation ID
234
  
235
  static ExtendedOperation.Builder newBuilder();
236
}
237

238
class ExtendedOperation.Error {
239
  String getCode();                     // Error code
240
  String getMessage();                  // Error message
241
  repeated ExtendedOperation.Error.ErrorDetail getErrorDetailsList();
242
  
243
  static Error.Builder newBuilder();
244
}
245

246
class ExtendedOperation.Warning {
247
  String getCode();                     // Warning code
248
  String getMessage();                  // Warning message
249
  repeated ExtendedOperation.Warning.WarningDataItem getDataList();
250
  
251
  static Warning.Builder newBuilder();
252
}
253
```
254

255
## Operation Response Mapping
256

257
### OperationResponseMapping
258

259
Maps operation response fields for different operation types.
260

261
```java { .api }
262
enum OperationResponseMapping {
263
  UNDEFINED(0),
264
  NAME(1),
265
  STATUS(2),
266
  ERROR_CODE(3),
267
  ERROR_MESSAGE(4);
268
  
269
  int getNumber();
270
  static OperationResponseMapping forNumber(int value);
271
}
272
```
273

274
## Usage Examples
275

276
### Audit Log Processing
277

278
```java
279
import com.google.cloud.audit.AuditLog;
280
import com.google.cloud.audit.AuthenticationInfo;
281
import com.google.cloud.audit.AuthorizationInfo;
282

283
public void processAuditLog(AuditLog auditLog) {
284
    System.out.println("Service: " + auditLog.getServiceName());
285
    System.out.println("Method: " + auditLog.getMethodName());
286
    System.out.println("Resource: " + auditLog.getResourceName());
287
    
288
    // Process authentication info
289
    if (auditLog.hasAuthenticationInfo()) {
290
        AuthenticationInfo authInfo = auditLog.getAuthenticationInfo();
291
        System.out.println("Principal: " + authInfo.getPrincipalEmail());
292
    }
293
    
294
    // Process authorization info
295
    for (AuthorizationInfo authzInfo : auditLog.getAuthorizationInfoList()) {
296
        System.out.printf("Permission %s on %s: %s\n",
297
            authzInfo.getPermission(),
298
            authzInfo.getResource(),
299
            authzInfo.getGranted() ? "GRANTED" : "DENIED");
300
    }
301
    
302
    // Check operation status
303
    if (auditLog.hasStatus()) {
304
        Status status = auditLog.getStatus();
305
        if (status.getCode() != 0) {
306
            System.err.println("Operation failed: " + status.getMessage());
307
        }
308
    }
309
}
310
```
311

312
### Location Management
313

314
```java
315
import com.google.cloud.location.Location;
316
import com.google.cloud.location.ListLocationsRequest;
317
import com.google.cloud.location.ListLocationsResponse;
318

319
public void listAvailableRegions(String projectName) {
320
    ListLocationsRequest request = ListLocationsRequest.newBuilder()
321
        .setName(projectName)
322
        .setPageSize(100)
323
        .build();
324
    
325
    ListLocationsResponse response = locationsClient.listLocations(request);
326
    
327
    System.out.println("Available regions:");
328
    for (Location location : response.getLocationsList()) {
329
        System.out.printf("- %s (%s): %s\n",
330
            location.getLocationId(),
331
            location.getDisplayName(),
332
            location.getName());
333
            
334
        // Print labels if available
335
        if (location.hasLabels()) {
336
            Struct labels = location.getLabels();
337
            System.out.println("  Labels: " + labels.toString());
338
        }
339
    }
340
}
341
```
342

343
### Policy Violation Handling
344

345
```java
346
import com.google.cloud.audit.PolicyViolationInfo;
347
import com.google.cloud.audit.OrgPolicyViolationInfo;
348
import com.google.cloud.audit.ViolationInfo;
349

350
public void handlePolicyViolations(PolicyViolationInfo policyViolationInfo) {
351
    if (policyViolationInfo.hasOrgPolicyViolationInfo()) {
352
        OrgPolicyViolationInfo orgViolation = policyViolationInfo.getOrgPolicyViolationInfo();
353
        
354
        System.out.println("Organization policy violation:");
355
        System.out.println("Resource type: " + orgViolation.getResourceType());
356
        
357
        for (String resourceTag : orgViolation.getResourceTagsList()) {
358
            System.out.println("Resource tag: " + resourceTag);
359
        }
360
        
361
        for (ViolationInfo violation : orgViolation.getViolationInfoList()) {
362
            System.out.printf("Constraint '%s' violated: %s\n",
363
                violation.getConstraint(),
364
                violation.getErrorMessage());
365
                
366
            System.out.println("Policy type: " + violation.getPolicyType());
367
        }
368
    }
369
}
370
```
371

372
### Extended Operation Monitoring
373

374
```java
375
import com.google.cloud.extended.operations.ExtendedOperation;
376

377
public void monitorExtendedOperation(ExtendedOperation operation) {
378
    System.out.println("Operation: " + operation.getName());
379
    System.out.println("Status: " + operation.getStatus());
380
    System.out.println("Type: " + operation.getOperationType());
381
    
382
    if (operation.hasProgress()) {
383
        System.out.println("Progress: " + operation.getProgress().getValue() + "%");
384
    }
385
    
386
    if (operation.hasUser()) {
387
        System.out.println("User: " + operation.getUser());
388
    }
389
    
390
    // Show timing information
391
    if (operation.hasInsertTime()) {
392
        System.out.println("Started: " + operation.getInsertTime());
393
    }
394
    if (operation.hasEndTime()) {
395
        System.out.println("Completed: " + operation.getEndTime());
396
    }
397
    
398
    // Handle errors
399
    if (!operation.getErrorsList().isEmpty()) {
400
        System.err.println("Errors:");
401
        for (ExtendedOperation.Error error : operation.getErrorsList()) {
402
            System.err.println("- " + error.getCode() + ": " + error.getMessage());
403
        }
404
    }
405
    
406
    // Handle warnings
407
    if (!operation.getWarningsList().isEmpty()) {
408
        System.out.println("Warnings:");
409
        for (ExtendedOperation.Warning warning : operation.getWarningsList()) {
410
            System.out.println("- " + warning.getCode() + ": " + warning.getMessage());
411
        }
412
    }
413
}
414
```
415

416
### Creating Audit Logs
417

418
```java
419
public AuditLog createAuditLog(String serviceName, String methodName, 
420
                              String resourceName, String principalEmail, 
421
                              boolean success) {
422
    
423
    AuthenticationInfo authInfo = AuthenticationInfo.newBuilder()
424
        .setPrincipalEmail(principalEmail)
425
        .build();
426
    
427
    RequestMetadata requestMetadata = RequestMetadata.newBuilder()
428
        .setCallerIp("192.168.1.100")
429
        .setCallerSuppliedUserAgent("MyApp/1.0")
430
        .build();
431
    
432
    Status status = Status.newBuilder()
433
        .setCode(success ? Code.OK.getNumber() : Code.INTERNAL.getNumber())
434
        .setMessage(success ? "Success" : "Operation failed")
435
        .build();
436
    
437
    return AuditLog.newBuilder()
438
        .setServiceName(serviceName)
439
        .setMethodName(methodName)
440
        .setResourceName(resourceName)
441
        .setAuthenticationInfo(authInfo)
442
        .setRequestMetadata(requestMetadata)
443
        .setStatus(status)
444
        .build();
445
}
446
```
447

448
## Best Practices
449

450
### Audit Log Security
451

452
1. **Sensitive Data**: Never log sensitive data like passwords or personal information in audit logs
453
2. **PII Handling**: Follow data protection regulations when logging personally identifiable information
454
3. **Access Control**: Restrict access to audit logs to authorized personnel only
455

456
### Location Services
457

458
1. **Caching**: Cache location information as it changes infrequently
459
2. **Validation**: Always validate location IDs before using them in API calls
460
3. **Fallbacks**: Have fallback logic for when preferred locations are unavailable
461

462
### Policy Violations
463

464
1. **Alerting**: Set up monitoring and alerting for policy violations
465
2. **Documentation**: Document all organization policies clearly
466
3. **Remediation**: Provide clear guidance on how to resolve violations