0
# Organization Events
1
2
Access organization-level service health events that may affect multiple projects within your organization. Organization events provide visibility into broader service health issues and their organizational impact across all projects under your organization.
3
4
## Capabilities
5
6
### List Organization Events
7
8
Retrieve a list of organization-level service health events with support for filtering, pagination, and different view levels.
9
10
```python { .api }
11
def list_organization_events(
12
request: ListOrganizationEventsRequest = None,
13
*,
14
parent: str = None,
15
retry: Retry = None,
16
timeout: float = None,
17
metadata: Sequence[Tuple[str, str]] = ()
18
) -> ListOrganizationEventsPager:
19
"""
20
Lists organization-level service health events.
21
22
Parameters:
23
- request: The request object containing all parameters
24
- parent: Required. Format: organizations/{org_id}/locations/{location}
25
- retry: Retry policy for the request
26
- timeout: Request timeout in seconds
27
- metadata: Additional metadata for the request
28
29
Returns:
30
ListOrganizationEventsPager: Iterator over OrganizationEvent objects
31
"""
32
```
33
34
**Usage Example:**
35
36
```python
37
from google.cloud.servicehealth import ServiceHealthClient, OrganizationEventView
38
39
client = ServiceHealthClient()
40
41
# List all organization events
42
parent = "organizations/123456789/locations/global"
43
org_events = client.list_organization_events(parent=parent)
44
45
for event in org_events:
46
print(f"Org Event: {event.title} - State: {event.state}")
47
48
# List with filtering and full view
49
active_events = client.list_organization_events(
50
parent=parent,
51
filter='state="ACTIVE"',
52
view=OrganizationEventView.ORGANIZATION_EVENT_VIEW_FULL
53
)
54
55
for event in active_events:
56
print(f"Event: {event.title}")
57
print(f"Description: {event.description}")
58
for impact in event.event_impacts:
59
print(f" Impact: {impact.product.product_name}")
60
```
61
62
### Get Organization Event
63
64
Retrieve detailed information about a specific organization-level service health event.
65
66
```python { .api }
67
def get_organization_event(
68
request: GetOrganizationEventRequest = None,
69
*,
70
name: str = None,
71
retry: Retry = None,
72
timeout: float = None,
73
metadata: Sequence[Tuple[str, str]] = ()
74
) -> OrganizationEvent:
75
"""
76
Gets details of a specific organization event.
77
78
Parameters:
79
- request: The request object containing all parameters
80
- name: Required. Format: organizations/{org_id}/locations/{location}/organizationEvents/{event_id}
81
- retry: Retry policy for the request
82
- timeout: Request timeout in seconds
83
- metadata: Additional metadata for the request
84
85
Returns:
86
OrganizationEvent: The organization event details
87
"""
88
```
89
90
**Usage Example:**
91
92
```python
93
# Get a specific organization event
94
event_name = "organizations/123456789/locations/global/organizationEvents/event-456"
95
org_event = client.get_organization_event(name=event_name)
96
97
print(f"Organization Event: {org_event.title}")
98
print(f"Description: {org_event.description}")
99
print(f"State: {org_event.state}")
100
print(f"Category: {org_event.category}")
101
102
# Check affected products and locations
103
for impact in org_event.event_impacts:
104
print(f"Affected Product: {impact.product.product_name}")
105
print(f"Affected Location: {impact.location.location_name}")
106
107
# Review event timeline
108
for update in org_event.updates:
109
print(f"Update ({update.update_time}): {update.title}")
110
if update.symptom:
111
print(f"Symptom: {update.symptom}")
112
```
113
114
## Request Types
115
116
```python { .api }
117
class ListOrganizationEventsRequest:
118
"""Request message for listing organization events."""
119
parent: str # Required: organizations/{org_id}/locations/{location}
120
page_size: int # Optional: 1-100, defaults to reasonable size
121
page_token: str # Optional: pagination token from previous response
122
filter: str # Optional: filter expression
123
view: OrganizationEventView # Optional: controls which fields are returned
124
125
class GetOrganizationEventRequest:
126
"""Request message for getting a specific organization event."""
127
name: str # Required: organizations/{org_id}/locations/{location}/organizationEvents/{event_id}
128
```
129
130
## Response Types
131
132
```python { .api }
133
class ListOrganizationEventsResponse:
134
"""Response message for listing organization events."""
135
organization_events: List[OrganizationEvent] # List of organization events
136
next_page_token: str # Token for retrieving next page
137
unreachable: List[str] # Locations that could not be reached
138
139
class OrganizationEvent:
140
"""Represents an organization-level service health event."""
141
name: str # Output only: Resource name
142
title: str # Output only: Event title
143
description: str # Output only: Detailed description
144
category: OrganizationEvent.EventCategory # Output only: Event category
145
detailed_category: OrganizationEvent.DetailedCategory # Output only: Detailed category
146
state: OrganizationEvent.State # Output only: Current event state
147
detailed_state: OrganizationEvent.DetailedState # Output only: Detailed state
148
event_impacts: List[EventImpact] # Output only: List of impacts
149
updates: List[EventUpdate] # Output only: Event updates (in FULL view)
150
parent_event: str # Output only: Parent event if this is a child
151
update_time: datetime # Output only: Last update time
152
start_time: datetime # Output only: Event start time
153
end_time: datetime # Output only: Event end time (if resolved)
154
next_update_time: datetime # Output only: Expected next update time
155
```
156
157
## Organization Event Enumerations
158
159
```python { .api }
160
class OrganizationEvent.EventCategory(Enum):
161
"""Category of the organization event."""
162
EVENT_CATEGORY_UNSPECIFIED = 0 # Unspecified category
163
INCIDENT = 2 # Service outage or degradation
164
165
class OrganizationEvent.DetailedCategory(Enum):
166
"""Detailed category information."""
167
DETAILED_CATEGORY_UNSPECIFIED = 0 # Unspecified detailed category
168
CONFIRMED_INCIDENT = 1 # Confirmed impact to Google Cloud product
169
EMERGING_INCIDENT = 2 # Under investigation for potential impact
170
171
class OrganizationEvent.State(Enum):
172
"""Current state of the organization event."""
173
STATE_UNSPECIFIED = 0 # Unspecified state
174
ACTIVE = 1 # Event is actively affecting Google Cloud product
175
CLOSED = 2 # Event is no longer affecting or merged with another
176
177
class OrganizationEvent.DetailedState(Enum):
178
"""Detailed state information."""
179
DETAILED_STATE_UNSPECIFIED = 0 # Unspecified detailed state
180
EMERGING = 1 # Event is under investigation
181
CONFIRMED = 2 # Event is confirmed and impacting service
182
RESOLVED = 3 # Event no longer affects the Google Cloud product
183
MERGED = 4 # Event merged into parent incident
184
AUTO_CLOSED = 9 # Event automatically closed by the system
185
FALSE_POSITIVE = 10 # Event was determined not to affect service
186
```
187
188
## Organization Event Views
189
190
```python { .api }
191
class OrganizationEventView(Enum):
192
"""Controls which fields are included in organization event responses."""
193
ORGANIZATION_EVENT_VIEW_UNSPECIFIED = 0 # Default to basic view
194
ORGANIZATION_EVENT_VIEW_BASIC = 1 # Basic fields without updates
195
ORGANIZATION_EVENT_VIEW_FULL = 2 # All fields including updates
196
```
197
198
## Filtering Organization Events
199
200
The `filter` parameter supports filtering expressions similar to project events:
201
202
**State filtering:**
203
```python
204
filter='state="ACTIVE"' # Only active events
205
filter='state="CLOSED"' # Only closed events
206
```
207
208
**Category filtering:**
209
```python
210
filter='category="INCIDENT"' # Only incidents
211
```
212
213
**Time range filtering:**
214
```python
215
filter='start_time>="2023-01-01T00:00:00Z"' # Events after date
216
filter='update_time<="2023-12-31T23:59:59Z"' # Events updated before date
217
```
218
219
**Product filtering:**
220
```python
221
filter='event_impacts.product.product_name="Compute Engine"' # Specific product
222
```
223
224
## Organization Event Monitoring
225
226
```python
227
from google.cloud.servicehealth import ServiceHealthClient
228
import time
229
230
def monitor_organization_events(organization_id: str):
231
"""Monitor active organization events with periodic updates."""
232
client = ServiceHealthClient()
233
parent = f"organizations/{organization_id}/locations/global"
234
235
while True:
236
# Get active organization events
237
active_events = client.list_organization_events(
238
parent=parent,
239
filter='state="ACTIVE"',
240
view=OrganizationEventView.ORGANIZATION_EVENT_VIEW_FULL
241
)
242
243
for event in active_events:
244
print(f"Active Event: {event.title}")
245
print(f"Last Update: {event.update_time}")
246
247
# Check for recent updates
248
if event.updates:
249
latest_update = event.updates[-1] # Most recent update
250
print(f"Latest Update: {latest_update.title}")
251
252
if latest_update.workaround:
253
print(f"Workaround Available: {latest_update.workaround}")
254
255
# Wait before next check
256
time.sleep(300) # Check every 5 minutes
257
258
# Usage
259
monitor_organization_events("123456789")
260
```
261
262
## Differences from Project Events
263
264
Organization events differ from project-level events in several ways:
265
266
1. **Scope**: Organization events affect multiple projects within an organization
267
2. **Visibility**: Require organization-level permissions to access
268
3. **Resource Names**: Use organization ID instead of project ID in resource paths
269
4. **Impact Assessment**: May affect resources across multiple projects
270
5. **Notification**: Typically used for organization-wide alerting and reporting