0
# Job Management
1

2
Complete job posting lifecycle management including creation, updates, deletion, listing, and advanced search with filtering, ranking, and analytics. Supports both individual operations and batch processing for efficient bulk operations with up to 200 jobs per batch operation.
3

4
## Capabilities
5

6
### Job Creation
7

8
Creates new job postings with comprehensive metadata including title, description, location, compensation, and custom attributes.
9

10
```python { .api }
11
def create_job(self, parent: str, job: Job) -> Job:
12
    """
13
    Creates a new job posting.
14

15
    Parameters:
16
    - parent (str): Tenant resource name where job will be created
17
    - job (Job): Job object with required fields (company, requisition_id, title, description)
18

19
    Returns:
20
    Job: Created job with generated resource name and derived information
21

22
    Raises:
23
    - InvalidArgument: Missing required fields or invalid values
24
    - AlreadyExists: Job with same requisition_id already exists
25
    - PermissionDenied: Insufficient permissions to create job
26
    """
27
```
28

29
**Usage Example:**
30

31
```python
32
from google.cloud.talent import JobServiceClient, Job, EmploymentType, JobLevel
33

34
client = JobServiceClient()
35

36
job = Job(
37
    company="projects/my-project/tenants/my-tenant/companies/company-123",
38
    requisition_id="req-software-eng-001",
39
    title="Senior Software Engineer",
40
    description="""
41
    <p>Join our engineering team to build scalable cloud solutions.</p>
42
    <h3>Requirements:</h3>
43
    <ul>
44
        <li>5+ years of Python experience</li>
45
        <li>Experience with cloud platforms</li>
46
        <li>Strong problem-solving skills</li>
47
    </ul>
48
    """,
49
    addresses=["1600 Amphitheatre Parkway, Mountain View, CA 94043"],
50
    employment_types=[EmploymentType.FULL_TIME],
51
    job_level=JobLevel.EXPERIENCED,
52
    qualifications="Bachelor's degree in Computer Science or equivalent experience"
53
)
54

55
created_job = client.create_job(
56
    parent="projects/my-project/tenants/my-tenant",
57
    job=job
58
)
59
```
60

61
### Job Retrieval
62

63
Retrieves individual job postings by resource name with configurable view levels for controlling the amount of data returned.
64

65
```python { .api }
66
def get_job(self, name: str) -> Job:
67
    """
68
    Retrieves a job by its resource name.
69

70
    Parameters:
71
    - name (str): Full job resource name
72

73
    Returns:
74
    Job: Complete job object with all fields
75

76
    Raises:
77
    - NotFound: Job does not exist
78
    - PermissionDenied: Insufficient permissions to view job
79
    """
80
```
81

82
### Job Updates
83

84
Updates existing job postings with field-level control using update masks to specify which fields should be modified.
85

86
```python { .api }
87
def update_job(self, job: Job, update_mask: FieldMask = None) -> Job:
88
    """
89
    Updates an existing job posting.
90

91
    Parameters:
92
    - job (Job): Job object with updated values and resource name
93
    - update_mask (FieldMask): Specifies which fields to update
94

95
    Returns:
96
    Job: Updated job object
97

98
    Raises:
99
    - NotFound: Job does not exist
100
    - InvalidArgument: Invalid field values or update mask
101
    - PermissionDenied: Insufficient permissions to update job
102
    """
103
```
104

105
**Usage Example:**
106

107
```python
108
from google.protobuf import field_mask_pb2
109

110
# Update job title and description only
111
job.title = "Staff Software Engineer"
112
job.description = "Updated job description with new requirements"
113

114
update_mask = field_mask_pb2.FieldMask(paths=["title", "description"])
115

116
updated_job = client.update_job(job=job, update_mask=update_mask)
117
```
118

119
### Job Deletion
120

121
Removes job postings from the system. Deleted jobs cannot be recovered and will no longer appear in search results.
122

123
```python { .api }
124
def delete_job(self, name: str) -> None:
125
    """
126
    Deletes a job posting.
127

128
    Parameters:
129
    - name (str): Full job resource name
130

131
    Raises:
132
    - NotFound: Job does not exist
133
    - PermissionDenied: Insufficient permissions to delete job
134
    """
135
```
136

137
### Job Listing
138

139
Lists job postings with pagination, filtering, and configurable view levels for efficient browsing of large job datasets.
140

141
```python { .api }
142
def list_jobs(self, parent: str, filter: str = None, page_size: int = None, 
143
              page_token: str = None, job_view: JobView = None) -> ListJobsResponse:
144
    """
145
    Lists jobs with optional filtering and pagination.
146

147
    Parameters:
148
    - parent (str): Tenant resource name
149
    - filter (str): Filter expression for job attributes
150
    - page_size (int): Maximum number of jobs to return (max 1000)
151
    - page_token (str): Token for pagination from previous response
152
    - job_view (JobView): Level of detail to return
153

154
    Returns:
155
    ListJobsResponse: Jobs list with pagination token and metadata
156

157
    Raises:
158
    - InvalidArgument: Invalid filter expression or page size
159
    - PermissionDenied: Insufficient permissions to list jobs
160
    """
161
```
162

163
**Usage Example:**
164

165
```python
166
from google.cloud.talent import JobView
167

168
# List all jobs with minimal details
169
response = client.list_jobs(
170
    parent="projects/my-project/tenants/my-tenant",
171
    job_view=JobView.JOB_VIEW_MINIMAL,
172
    page_size=50
173
)
174

175
for job in response.jobs:
176
    print(f"Job: {job.title} at {job.company}")
177

178
# Continue pagination if needed
179
if response.next_page_token:
180
    next_response = client.list_jobs(
181
        parent="projects/my-project/tenants/my-tenant",
182
        page_token=response.next_page_token,
183
        page_size=50
184
    )
185
```
186

187
### Advanced Job Search
188

189
Performs sophisticated job searches with text queries, geographic filtering, compensation ranges, and histogram analytics for building advanced job search experiences.
190

191
```python { .api }
192
def search_jobs(self, request: SearchJobsRequest) -> SearchJobsResponse:
193
    """
194
    Searches for jobs with advanced filtering and ranking.
195

196
    Parameters:
197
    - request (SearchJobsRequest): Complete search request with query, filters, and options
198

199
    Returns:
200
    SearchJobsResponse: Matching jobs with ranking, metadata, and histogram results
201

202
    Raises:
203
    - InvalidArgument: Invalid search parameters or query syntax
204
    - PermissionDenied: Insufficient permissions to search jobs
205
    """
206
```
207

208
**Usage Example:**
209

210
```python
211
from google.cloud.talent import (
212
    SearchJobsRequest, JobQuery, LocationFilter, CompensationFilter,
213
    HistogramQuery, SearchMode
214
)
215

216
search_request = SearchJobsRequest(
217
    parent="projects/my-project/tenants/my-tenant",
218
    search_mode=SearchMode.JOB_SEARCH,
219
    job_query=JobQuery(
220
        query="python software engineer",
221
        location_filters=[
222
            LocationFilter(
223
                address="San Francisco, CA",
224
                distance_in_miles=25.0
225
            )
226
        ],
227
        compensation_filter=CompensationFilter(
228
            type_=CompensationFilter.FilterType.ANNUALIZED_BASE_AMOUNT,
229
            range_=CompensationRange(
230
                max_compensation=Money(currency_code="USD", units=150000),
231
                min_compensation=Money(currency_code="USD", units=100000)
232
            )
233
        )
234
    ),
235
    histogram_queries=[
236
        HistogramQuery(histogram_query="employment_type"),
237
        HistogramQuery(histogram_query="company_size")
238
    ],
239
    job_view=JobView.JOB_VIEW_SMALL,
240
    page_size=20
241
)
242

243
search_response = client.search_jobs(search_request)
244

245
for matching_job in search_response.matching_jobs:
246
    job = matching_job.job
247
    print(f"Job: {job.title} at {job.company}")
248
    print(f"Match score: {matching_job.match_type}")
249

250
# Process histogram results for faceted search UI
251
for histogram_result in search_response.histogram_query_results:
252
    print(f"Facet: {histogram_result.histogram_query}")
253
    for bucket in histogram_result.histogram:
254
        print(f"  {bucket.range_}: {bucket.count} jobs")
255
```
256

257
### Job Search for Alerts
258

259
Specialized job search designed for passive job seekers, such as users receiving email alerts about potential opportunities. Uses different algorithmic adjustments optimized for targeting passive candidates with different ranking and visibility constraints.
260

261
```python { .api }
262
def search_jobs_for_alert(self, request: SearchJobsRequest) -> SearchJobsResponse:
263
    """
264
    Searches for jobs with algorithms optimized for passive job seekers.
265
    
266
    This method is specifically designed for targeting passive job seekers 
267
    (e.g., users signed up for job alert emails) with algorithmic adjustments
268
    that differ from active job search scenarios.
269

270
    Parameters:
271
    - request (SearchJobsRequest): Search request with query and filtering options
272

273
    Returns:
274
    SearchJobsResponse: Jobs ranked for passive job seeker scenarios
275

276
    Raises:
277
    - InvalidArgument: Invalid search parameters
278
    - PermissionDenied: Insufficient permissions to search jobs
279
    """
280
```
281

282
**Usage Example:**
283

284
```python
285
from google.cloud.talent import SearchJobsRequest, JobQuery, LocationFilter
286

287
# Create search request optimized for job alerts
288
alert_request = SearchJobsRequest(
289
    parent="projects/my-project/tenants/my-tenant",
290
    job_query=JobQuery(
291
        query="software engineer python",
292
        location_filters=[
293
            LocationFilter(
294
                address="San Francisco Bay Area, CA",
295
                distance_in_miles=50.0
296
            )
297
        ]
298
    ),
299
    job_view=JobView.JOB_VIEW_SMALL,
300
    page_size=10
301
)
302

303
# Search with alert-optimized algorithms
304
alert_response = client.search_jobs_for_alert(alert_request)
305

306
for matching_job in alert_response.matching_jobs:
307
    job = matching_job.job
308
    print(f"Alert job: {job.title} at {job.company}")
309
```
310

311
### Batch Job Operations
312

313
Efficiently processes multiple jobs in single operations for bulk creation, updates, or deletion with up to 200 jobs per batch operation.
314

315
```python { .api }
316
def batch_create_jobs(self, parent: str, jobs: List[Job]) -> Operation:
317
    """
318
    Creates multiple jobs in a single batch operation.
319

320
    Parameters:
321
    - parent (str): Tenant resource name
322
    - jobs (List[Job]): List of jobs to create (max 200)
323

324
    Returns:
325
    Operation: Long-running operation for tracking batch progress
326

327
    Raises:
328
    - InvalidArgument: Too many jobs or invalid job data
329
    - PermissionDenied: Insufficient permissions for batch operations
330
    """
331

332
def batch_update_jobs(self, parent: str, jobs: List[Job]) -> Operation:
333
    """
334
    Updates multiple jobs in a single batch operation.
335

336
    Parameters:
337
    - parent (str): Tenant resource name
338
    - jobs (List[Job]): List of jobs to update with resource names (max 200)
339

340
    Returns:
341
    Operation: Long-running operation for tracking batch progress
342
    """
343

344
def batch_delete_jobs(self, parent: str, names: List[str]) -> Operation:
345
    """
346
    Deletes multiple jobs in a single batch operation.
347

348
    Parameters:
349
    - parent (str): Tenant resource name
350
    - names (List[str]): List of job resource names to delete (max 200)
351

352
    Returns:
353
    Operation: Long-running operation for tracking batch progress
354
    """
355
```
356

357
**Usage Example:**
358

359
```python
360
from google.cloud.talent import Job
361
import time
362

363
# Batch create multiple jobs
364
jobs_to_create = []
365
for i in range(10):
366
    job = Job(
367
        company="projects/my-project/tenants/my-tenant/companies/company-123",
368
        requisition_id=f"batch-job-{i}",
369
        title=f"Software Engineer {i}",
370
        description="Batch created job posting",
371
        addresses=["Remote"]
372
    )
373
    jobs_to_create.append(job)
374

375
# Start batch creation
376
operation = client.batch_create_jobs(
377
    parent="projects/my-project/tenants/my-tenant",
378
    jobs=jobs_to_create
379
)
380

381
# Monitor operation progress
382
while not operation.done():
383
    print("Batch operation in progress...")
384
    time.sleep(5)
385
    operation = client.get_operation(name=operation.name)
386

387
# Get final results
388
if operation.done():
389
    if operation.error:
390
        print(f"Batch operation failed: {operation.error}")
391
    else:
392
        result = operation.result()
393
        print(f"Successfully created {len(result.job_results)} jobs")
394
```
395

396
### Long-Running Operation Management
397

398
Tracks and manages the status of batch operations and other long-running tasks.
399

400
```python { .api }
401
def get_operation(self, request: GetOperationRequest) -> Operation:
402
    """
403
    Gets the status of a long-running operation.
404

405
    Parameters:
406
    - request (GetOperationRequest): Operation name and metadata
407

408
    Returns:
409
    Operation: Current operation status with progress and results
410

411
    Raises:
412
    - NotFound: Operation does not exist
413
    - PermissionDenied: Insufficient permissions to view operation
414
    """
415
```
416

417
## Request and Response Types
418

419
### Core Request Types
420

421
```python { .api }
422
class CreateJobRequest:
423
    parent: str = None  # Tenant resource name
424
    job: Job = None  # Job to create
425

426
class GetJobRequest:
427
    name: str = None  # Job resource name
428

429
class UpdateJobRequest:
430
    job: Job = None  # Job with updates
431
    update_mask: FieldMask = None  # Fields to update
432

433
class DeleteJobRequest:
434
    name: str = None  # Job resource name
435

436
class ListJobsRequest:
437
    parent: str = None  # Tenant resource name
438
    filter: str = None  # Filter expression
439
    page_size: int = None  # Page size (max 1000)
440
    page_token: str = None  # Pagination token
441
    job_view: JobView = None  # Detail level
442

443
class SearchJobsRequest:
444
    parent: str = None  # Tenant resource name
445
    search_mode: SearchMode = None  # Search mode
446
    job_query: JobQuery = None  # Search query and filters
447
    enable_broadening: bool = None  # Enable query broadening
448
    histogram_queries: List[HistogramQuery] = None  # Faceted search
449
    job_view: JobView = None  # Detail level
450
    offset: int = None  # Result offset
451
    page_size: int = None  # Page size (max 100)
452
    page_token: str = None  # Pagination token
453
    order_by: str = None  # Sort order
454
    diversification_level: DiversificationLevel = None  # Result diversity
455
    custom_ranking_info: CustomRankingInfo = None  # Custom ranking
456
```
457

458
### Core Response Types
459

460
```python { .api }
461
class ListJobsResponse:
462
    jobs: List[Job] = None  # List of jobs
463
    next_page_token: str = None  # Pagination token
464
    metadata: ResponseMetadata = None  # Response metadata
465

466
class SearchJobsResponse:
467
    matching_jobs: List[MatchingJob] = None  # Jobs with match info
468
    histogram_query_results: List[HistogramQueryResult] = None  # Facet results
469
    next_page_token: str = None  # Pagination token
470
    location_filters: List[Location] = None  # Matched locations
471
    spell_correction: SpellCheckResult = None  # Query corrections
472
    metadata: ResponseMetadata = None  # Response metadata
473
    total_size: int = None  # Total result count
474
    broadened_query_jobs_count: int = None  # Broadened results count
475

476
class BatchCreateJobsResponse:
477
    job_results: List[JobResult] = None  # Individual job results
478

479
class BatchUpdateJobsResponse:
480
    job_results: List[JobResult] = None  # Individual job results
481

482
class BatchDeleteJobsResponse:
483
    job_results: List[JobResult] = None  # Individual job results
484
```
485

486
### Supporting Types
487

488
```python { .api }
489
class JobResult:
490
    job: Job = None  # Job data
491
    status: Status = None  # Operation status
492

493
class MatchingJob:
494
    job: Job = None  # Matched job
495
    job_summary: str = None  # Highlighted summary
496
    job_title_snippet: str = None  # Highlighted title
497
    search_text_snippet: str = None  # Highlighted text
498
    commute_info: CommuteInfo = None  # Commute information
499

500
class JobView(Enum):
501
    JOB_VIEW_UNSPECIFIED = 0
502
    JOB_VIEW_ID_ONLY = 1
503
    JOB_VIEW_MINIMAL = 2
504
    JOB_VIEW_SMALL = 3
505
    JOB_VIEW_FULL = 4
506

507
class SearchMode(Enum):
508
    JOB_SEARCH = 1
509
    FEATURED_JOB_SEARCH = 2
510
```
511

512
## Error Handling
513

514
Job management operations can raise several types of exceptions:
515

516
```python
517
from google.api_core import exceptions
518

519
try:
520
    job = client.create_job(parent=parent, job=job_data)
521
except exceptions.InvalidArgument as e:
522
    # Handle validation errors
523
    print(f"Invalid job data: {e}")
524
except exceptions.AlreadyExists as e:
525
    # Handle duplicate requisition_id
526
    print(f"Job already exists: {e}")
527
except exceptions.ResourceExhausted as e:
528
    # Handle quota limits
529
    print(f"Quota exceeded: {e}")
530
except exceptions.PermissionDenied as e:
531
    # Handle authorization errors
532
    print(f"Access denied: {e}")
533
```
534

535
Common error scenarios:
536
- **InvalidArgument**: Missing required fields, invalid field values, malformed resource names
537
- **AlreadyExists**: Duplicate requisition_id within the same company
538
- **NotFound**: Job, company, or tenant does not exist
539
- **PermissionDenied**: Insufficient IAM permissions
540
- **ResourceExhausted**: API quota limits exceeded
541
- **FailedPrecondition**: Resource in invalid state for operation