feat(storage-batch): Improve Batch Operation API samples (Documentation & Error Handling)

thiyaguk09 · thiyaguk09 · commit 7dceecc7a280 · 2025-10-24T12:21:49.000+05:30
Improve the robustness and clarity of the Storage Batch Operations API
samples:

* **Error Handling:** Wraps all asynchronous Batch Operations API
samples (Create, Get, List, Cancel) in `try...catch` blocks for
production readiness.
* **Specific Diagnostics:** Adds specific gRPC error code checks
(`NOT_FOUND`, `FAILED_PRECONDITION`) within the `catch` blocks to
provide detailed diagnostic feedback to users regarding job state or
non-existence.
* **Documentation:** Clarifies JSDoc for all function parameters (e.g.,
`projectId`, `jobId`, `objectPrefix`), ensuring examples and types are
clear for developers.
diff --git a/storagebatchoperations/cancelJob.js b/storagebatchoperations/cancelJob.js
@@ -23,16 +23,19 @@
 
 function main(projectId, jobId) {
   // [START storage_batch_cancel_job]
+
   /**
-   * TODO(developer): Uncomment these variables before running the sample.
+   * Cancel a batch job instance.
+   *
+   * The operation to cancel a batch job instance in Google Cloud Storage (GCS) is used to stop
+   * a running or queued asynchronous task that is currently processing a large number of GCS objects.
+   *
+   * @param {string} projectId The Google Cloud project ID.
+   * Example: 'my-project-id'
+   * @param {string} jobId A unique identifier for this job.
+   * Example: '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5'
    */
 
-  // Your Google Cloud project ID.
-  // const projectId = 'my-project-id';
-
-  // A unique identifier for this job.
-  // const jobId = '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5';
-
   // Imports the Control library
   const {StorageBatchOperationsClient} =
     require('@google-cloud/storagebatchoperations').v1;
@@ -52,13 +55,30 @@ function main(projectId, jobId) {
     try {
       await client.cancelJob(request);
       console.log(`Cancelled job: ${name}`);
-    } catch (err) {
+    } catch (error) {
       // This might be expected if the job completed quickly or failed creation
-      console.log(`INFO: cancelJob threw: ${err.message}`);
+      console.error(
+        `Error canceling batch jobs for jobId ${jobId}:`,
+        error.message
+      );
+
+      if (error.code === 5) {
+        // NOT_FOUND (gRPC code 5) error can occur if the batch job does not exist.
+        console.error(
+          `Ensure the job '${jobId}' exists in project '${projectId}'.`
+        );
+      } else if (error.code === 9) {
+        // FAILED_PRECONDITION (gRPC code 9) can occur if the job is already being cancelled
+        // or is not in a RUNNING state that allows the cancel operation.
+        console.error(
+          `Batch job '${jobId}' may not be in a state that allows canceling (e.g., must be RUNNING).`
+        );
+      }
+      throw error;
     }
   }
 
-  cancelJob().catch(console.error);
+  cancelJob();
   // [END storage_batch_cancel_job]
 }
 
diff --git a/storagebatchoperations/createJob.js b/storagebatchoperations/createJob.js
@@ -23,22 +23,20 @@
 
 function main(projectId, jobId, bucketName, objectPrefix) {
   // [START storage_batch_create_job]
+
   /**
-   * TODO(developer): Uncomment these variables before running the sample.
+   * Create a new batch job instance.
+   *
+   * @param {string} projectId Your Google Cloud project ID.
+   * Example: 'my-project-id'
+   * @param {string} bucketName The name of your GCS bucket.
+   * Example: 'your-gcp-bucket-name'
+   * @param {string} jobId A unique identifier for this job.
+   * Example: '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5'
+   * @param {string} objectPrefix The prefix of objects to include in the operation.
+   * Example: 'prefix1'
    */
 
-  // Your Google Cloud project ID.
-  // const projectId = 'my-project-id';
-
-  // The name of your GCS bucket
-  // const bucketName = 'bucketName';
-
-  // A unique identifier for this job.
-  // const jobId = '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5';
-
-  // The prefix of objects to include in the operation.
-  // const objectPrefix = 'prefix1';
-
   // Imports the Control library
   const {StorageBatchOperationsClient} =
     require('@google-cloud/storagebatchoperations').v1;
@@ -70,10 +68,18 @@ function main(projectId, jobId, bucketName, objectPrefix) {
       },
     };
 
-    // Run request
-    const [operation] = await client.createJob(request);
-    const [response] = await operation.promise();
-    console.log(`Created job: ${response.name}`);
+    try {
+      // Run the request, which returns an Operation object
+      const [operation] = await client.createJob(request);
+      console.log(`Waiting for operation ${operation.name} to complete...`);
+
+      // Wait for the operation to complete and get the final resource
+      const [response] = await operation.promise();
+      console.log(`Created job: ${response.name}`);
+    } catch (error) {
+      console.error('Failed to create batch job:', error.message);
+      throw error;
+    }
   }
 
   createJob();
diff --git a/storagebatchoperations/deleteJob.js b/storagebatchoperations/deleteJob.js
@@ -24,15 +24,17 @@
 function main(projectId, jobId) {
   // [START storage_batch_delete_job]
   /**
-   * TODO(developer): Uncomment these variables before running the sample.
+   * Delete a batch job instance.
+   *
+   * This operation is used to remove a completed, failed, or cancelled Batch Operation
+   * job from the system's list. It is essentially a cleanup action.
+   *
+   * @param {string} projectId Your Google Cloud project ID.
+   * Example: 'my-project-id'
+   * @param {string} jobId A unique identifier for this job.
+   * Example: '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5'
    */
 
-  // Your Google Cloud project ID.
-  // const projectId = 'my-project-id';
-
-  // A unique identifier for this job.
-  // const jobId = '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5';
-
   // Imports the Control library
   const {StorageBatchOperationsClient} =
     require('@google-cloud/storagebatchoperations').v1;
@@ -48,9 +50,24 @@ function main(projectId, jobId) {
       name,
     };
 
-    // Run request
-    await client.deleteJob(request);
-    console.log(`Deleted job: ${name}`);
+    try {
+      // Run request
+      await client.deleteJob(request);
+      console.log(`Deleted job: ${name}`);
+    } catch (error) {
+      console.error(
+        `Error deleting batch jobs for jobId ${jobId}:`,
+        error.message
+      );
+
+      if (error.code === 5) {
+        // NOT_FOUND (gRPC code 5) error can occur if the batch job does not exist.
+        console.error(
+          `Ensure the job '${jobId}' exists in project '${projectId}'.`
+        );
+      }
+      throw error;
+    }
   }
 
   deleteJob();
diff --git a/storagebatchoperations/getJob.js b/storagebatchoperations/getJob.js
@@ -24,15 +24,18 @@
 function main(projectId, jobId) {
   // [START storage_batch_get_job]
   /**
-   * TODO(developer): Uncomment these variables before running the sample.
+   * Retrieves details of a specific batch job instance.
+   *
+   * This operation is used to retrieve the detailed current state, execution status,
+   * and original configuration of a specific Batch Operation job that was previously
+   * created for a Google Cloud Storage bucket.
+   *
+   * @param {string} projectId Your Google Cloud project ID.
+   * Example: 'my-project-id'
+   * @param {string} jobId A unique identifier for this job.
+   * Example: '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5'
    */
 
-  // Your Google Cloud project ID.
-  // const projectId = 'my-project-id';
-
-  // A unique identifier for this job.
-  // const jobId = '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5';
-
   // Imports the Control library
   const {StorageBatchOperationsClient} =
     require('@google-cloud/storagebatchoperations').v1;
@@ -48,9 +51,29 @@ function main(projectId, jobId) {
       name,
     };
 
-    // Run request
-    const [response] = await client.getJob(request);
-    console.log(`Got job: ${response.name}`);
+    try {
+      // Run request
+      const [response] = await client.getJob(request);
+      console.log(`Batch job details for '${jobId}':`);
+      console.log(`  Name: ${response.name}`);
+      console.log(`  State: ${response.state}`);
+      console.log(
+        `  Create Time: ${new Date(response.createTime.seconds * 1000).toISOString()}`
+      );
+    } catch (error) {
+      console.error(
+        `Error retrieving batch jobs for jobId ${jobId}:`,
+        error.message
+      );
+
+      if (error.code === 5) {
+        // NOT_FOUND (gRPC code 5) error can occur if the batch job does not exist.
+        console.error(
+          `Ensure the job '${jobId}' exists in project '${projectId}'.`
+        );
+      }
+      throw error;
+    }
   }
 
   getJob();
diff --git a/storagebatchoperations/listJobs.js b/storagebatchoperations/listJobs.js
@@ -24,12 +24,16 @@
 function main(projectId) {
   // [START storage_batch_list_jobs]
   /**
-   * TODO(developer): Uncomment these variables before running the sample.
+   * Lists all Jobs operation is used to query the status and configuration of all
+   * Storage Batch Operations jobs within a specific Google Cloud project.
+   * This feature is essential for tasks that affect a large number of objects,
+   * such as changing storage classes, deleting objects, or running custom functions
+   * on object metadata.
+   *
+   * @param {string} projectId Your Google Cloud project ID.
+   * Example: 'my-project-id'
    */
 
-  // Your Google Cloud project ID.
-  // const projectId = 'my-project-id';
-
   // Imports the Control library
   const {StorageBatchOperationsClient} =
     require('@google-cloud/storagebatchoperations').v1;
@@ -45,10 +49,26 @@ function main(projectId) {
       parent,
     };
 
-    // Run request
-    const [response] = await client.listJobs(request);
-    for (const job of response) {
-      console.log(job.name);
+    try {
+      // Run request. The response is an array where the first element is the list of jobs.
+      const [response] = await client.listJobs(request);
+      if (response && response.length > 0) {
+        console.log(
+          `Found ${response.length} batch jobs for project: ${projectId}`
+        );
+        for (const job of response) {
+          console.log(job.name);
+        }
+      } else {
+        // Case: Successful but empty list (No batch jobs found)
+        console.log(`No batch jobs found for project: ${projectId}.`);
+      }
+    } catch (error) {
+      console.error(
+        `Error listing batch jobs for project ${projectId}:`,
+        error.message
+      );
+      throw error;
     }
   }
 
diff --git a/storagebatchoperations/quickstart.js b/storagebatchoperations/quickstart.js
@@ -29,13 +29,17 @@ async function main(projectId, jobId) {
     require('@google-cloud/storagebatchoperations').v1;
 
   /**
-   * TODO(developer): Uncomment the following lines before running the sample.
+   * Retrieves details of a specific batch job instance.
+   *
+   * This operation is used to retrieve the detailed current state, execution status,
+   * and original configuration of a specific Batch Operation job that was previously
+   * created for a Google Cloud Storage bucket.
+   *
+   * @param {string} projectId Your Google Cloud project ID.
+   * Example: 'my-project-id'
+   * @param {string} jobId A unique identifier for this job.
+   * Example: '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5'
    */
-  // Your Google Cloud project ID.
-  // const projectId = 'my-project-id';
-
-  // A unique identifier for this job.
-  // const jobId = '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5';
 
   // Creates a client
   const client = new StorageBatchOperationsClient();
@@ -48,9 +52,29 @@ async function main(projectId, jobId) {
       name,
     };
 
-    // Run request
-    const [response] = await client.getJob(request);
-    console.log(`Got job: ${response.name}`);
+    try {
+      // Run request
+      const [response] = await client.getJob(request);
+      console.log(`Batch job details for '${jobId}':`);
+      console.log(`  Name: ${response.name}`);
+      console.log(`  State: ${response.state}`);
+      console.log(
+        `  Create Time: ${new Date(response.createTime.seconds * 1000).toISOString()}`
+      );
+    } catch (error) {
+      console.error(
+        `Error retrieving batch jobs for jobId ${jobId}:`,
+        error.message
+      );
+
+      if (error.code === 5) {
+        // NOT_FOUND (gRPC code 5) error can occur if the batch job does not exist.
+        console.error(
+          `Ensure the job '${jobId}' exists in project '${projectId}'.`
+        );
+      }
+      throw error;
+    }
   }
   quickstart();
   // [END storage_batch_quickstart]
diff --git a/storagebatchoperations/system-test/storagebatchoperations.test.js b/storagebatchoperations/system-test/storagebatchoperations.test.js
@@ -22,7 +22,7 @@ const execSync = cmd => cp.execSync(cmd, {encoding: 'utf-8'});
 const projectId = process.env.GCLOUD_PROJECT;
 const bucketPrefix = 'sbo-samples';
 const bucketName = `${bucketPrefix}-${uuid.v4()}`;
-const storage = new Storage();
+const storage = new Storage(projectId);
 const bucket = new Bucket(storage, bucketName);
 const jobId = uuid.v4();
 const jobName = `projects/${projectId}/locations/global/jobs/${jobId}`;
@@ -58,24 +58,36 @@ describe('Batch Operations', () => {
 
   it('should run quickstart', async () => {
     const output = execSync(`node quickstart.js ${projectId} ${jobId}`);
-    assert.match(output, /Got job:/);
+    const detailsHeader = `Batch job details for '${jobId}':`;
+    assert.match(output, new RegExp(detailsHeader));
+    assert.match(output, /Name:/);
     assert.match(output, new RegExp(jobName));
+    assert.match(output, /State:/);
+    assert.match(output, /Create Time:/);
   });
 
   it('should get a job', async () => {
     const output = execSync(`node getJob.js ${projectId} ${jobId}`);
-    assert.match(output, /Got job:/);
+    const detailsHeader = `Batch job details for '${jobId}':`;
+    assert.match(output, new RegExp(detailsHeader));
+    assert.match(output, /Name:/);
     assert.match(output, new RegExp(jobName));
+    assert.match(output, /State:/);
+    assert.match(output, /Create Time:/);
   });
 
-  it('should cancel a job', async () => {
+  it('should cancel a job (or gracefully handle terminal state)', async () => {
     try {
       const output = execSync(`node cancelJob.js ${projectId} ${jobId}`);
       assert.match(output, /Cancelled job:/);
       assert.match(output, new RegExp(jobName));
     } catch (error) {
       // This might be expected if the job completed quickly or failed creation
-      assert.match(error.message, /INFO: cancelJob threw: /);
+      const errorMessage = error.stderr.toString();
+      assert.match(
+        errorMessage,
+        /9 FAILED_PRECONDITION: Job run.* is in a terminal state and can not be changed./
+      );
     }
   });
 
