[quantum] Migrate quantum projects to use snippets extraction (#33198)

### Packages impacted by this PR - @azure/quantum-jobs ### Issues associated with this PR - #32416 ### Describe the problem that is addressed by this PR Updates all projects under `quantum` to use snippets extraction. ### What are the possible designs available to address the problem? If there are more than one possible design, why was the one in this PR chosen? ### Are there test cases added in this PR? _(If not, why?)_ ### Provide a list of related PRs _(if any)_ ### Command used to generate this PR:**_(Applicable only to SDK release request PRs)_ ### Checklists - [ ] Added impacted package name to the issue description - [ ] Does this PR needs any fixes in the SDK Generator?** _(If so, create an Issue in the [Autorest/typescript](https://github.com/Azure/autorest.typescript) repository and link it here)_ - [ ] Added a changelog (if necessary)
Azure · Feb 26, 2025 · c50254b · c50254b
1 parent e37e425
commit c50254b
Show file tree

Hide file tree

Showing 8 changed files with 469 additions and 110 deletions.
diff --git a/sdk/quantum/quantum-jobs/CHANGELOG.md b/sdk/quantum/quantum-jobs/CHANGELOG.md
@@ -1,10 +1,13 @@
+<!-- dev-tool snippets ignore -->
+
 # Release History
 
 ## 1.0.0-beta.2 (Unreleased)
 
 ### Breaking Changes
 
 - Migrated to the Core v2 HTTP pipeline. As a result of this migration:
+
   - The response types no longer contain the raw response `_response`. To access the raw response, an `onResponse` callback has to be passed in the request options bag, for example:
 
     ```ts

diff --git a/sdk/quantum/quantum-jobs/README.md b/sdk/quantum/quantum-jobs/README.md
@@ -63,44 +63,68 @@ Create an instance of the QuantumJobClient by passing in these parameters:
 - [Storage Container Name][blob-storage] - your blob storage
 - [Credential][credentials] - used to authenticate
 
-```Javascript Snippet
-    const credential = new DefaultAzureCredential();
-
-    // Create a QuantumJobClient
-    const subscriptionId = "your_subscription_id";
-    const resourceGroupName = "your_resource_group_name";
-    const workspaceName = "your_quantum_workspace_name";
-    const storageContainerName = "mycontainer";
-    const location = "westus"; //"your_location";
-    const endpoint = "https://" + location + ".quantum.azure.com";
-
-    const quantumJobClient = new QuantumJobClient(
-      credential,
-      subscriptionId,
-      resourceGroupName,
-      workspaceName,
-      {
-        endpoint: endpoint,
-        credentialScopes: "https://quantum.microsoft.com/.default"
-      }
-    );
+```ts snippet:ReadmeSampleCreateClient_TokenCredential
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+
+const credential = new DefaultAzureCredential();
+
+// Create a QuantumJobClient
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
 ```
 
 ### Get Container SAS URI
 
 Create a storage container to put your data.
 
-```Javascript Snippet
-    // Get container Uri with SAS key
-    const containerUri = (
-      await quantumJobClient.storage.sasUri({
-        containerName: storageContainerName
-      })
-    ).sasUri;
-
-    // Create container if not exists
-    const containerClient = new ContainerClient(containerUri);
-    await containerClient.createIfNotExists();
+```ts snippet:ReadmeSampleCreateContainer
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+import { ContainerClient } from "@azure/storage-blob";
+
+const credential = new DefaultAzureCredential();
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const storageContainerName = "containername";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
+
+// Get container Uri with SAS key
+const containerUri = (
+  await quantumJobClient.storage.sasUri({
+    containerName: storageContainerName,
+  })
+).sasUri;
+
+// Create container if not exists
+const containerClient = new ContainerClient(containerUri);
+await containerClient.createIfNotExists();
 ```
 
 ### Compile your quantum program into QIR
@@ -123,82 +147,166 @@ We will use the QIR bitcode sample (`BellState.bc` in the samples folder), compi
 
 Using the SAS URI, upload the QIR bitcode input data to the blob client.
 
-```Javascript Snippet
-    // Get input data blob Uri with SAS key
-    const blobName = "myjobinput.bc";
-    const inputDataUri = (
-      await quantumJobClient.storage.sasUri({
-        containerName: storageContainerName,
-        blobName: blobName
-      })
-    ).sasUri;
-
-    // Upload input data to blob
-    const blobClient = new BlockBlobClient(inputDataUri);
-    const problemFilename = "BellState.bc";
-    const fileContent = fs.readFileSync(problemFilename, "utf8");
-    const blobOptions = {
-      blobHTTPHeaders: {
-        blobContentType: "qir.v1",
-      },
-    };
-    await blobClient.upload(fileContent, Buffer.byteLength(fileContent), blobOptions);
+```ts snippet:ReadmeSampleUploadInputData
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+import { BlockBlobClient } from "@azure/storage-blob";
+import { readFileSync } from "node:fs";
+
+const credential = new DefaultAzureCredential();
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const storageContainerName = "containername";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
+
+// Get input data blob Uri with SAS key
+const blobName = "myjobinput.bc";
+const inputDataUri = (
+  await quantumJobClient.storage.sasUri({
+    containerName: storageContainerName,
+    blobName: blobName,
+  })
+).sasUri;
+
+// Upload input data to blob
+const blobClient = new BlockBlobClient(inputDataUri);
+const problemFilename = "BellState.bc";
+const fileContent = readFileSync(problemFilename, "utf8");
+const blobOptions = {
+  blobHTTPHeaders: {
+    blobContentType: "qir.v1",
+  },
+};
+await blobClient.upload(fileContent, Buffer.byteLength(fileContent), blobOptions);
 ```
 
 ### Create The Job
 
 Now that you've uploaded your problem definition to Azure Storage, you can use `jobs.create` to define an Azure Quantum job.
 
-```Javascript Snippet
-    const randomId = `${Math.floor(Math.random() * 10000 + 1)}`;
-
-    // Submit job
-    const jobId = `job-${randomId}`;
-    const jobName = `jobName-${randomId}`;
-    const inputDataFormat = "qir.v1";
-    const outputDataFormat = "microsoft.quantum-results.v1";
-    const providerId = "quantinuum";
-    const target = "quantinuum.sim.h1-1e";
-    const inputParams = {
-      "entryPoint": "ENTRYPOINT__BellState",
-      "arguments": [],
-      "targetCapability": "AdaptiveExecution",
-    };
-    const createJobDetails = {
-      containerUri: containerUri,
-      inputDataFormat: inputDataFormat,
-      providerId: providerId,
-      target: target,
-      id: jobId,
-      inputDataUri: inputDataUri,
-      name: jobName,
-      outputDataFormat: outputDataFormat,
-      inputParams: inputParams
-    };
-    const createdJob = await quantumJobClient.jobs.create(jobId, createJobDetails);
+```ts snippet:ReadmeSampleCreateJob
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+
+const credential = new DefaultAzureCredential();
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
+
+const randomId = `${Math.floor(Math.random() * 10000 + 1)}`;
+
+// Submit job
+const jobId = `job-${randomId}`;
+const jobName = `jobName-${randomId}`;
+const inputDataFormat = "qir.v1";
+const outputDataFormat = "microsoft.quantum-results.v1";
+const providerId = "quantinuum";
+const target = "quantinuum.sim.h1-1e";
+const inputParams = {
+  entryPoint: "ENTRYPOINT__BellState",
+  arguments: [],
+  targetCapability: "AdaptiveExecution",
+};
+const createJobDetails = {
+  containerUri: "https://<container-uri>",
+  inputDataFormat: inputDataFormat,
+  providerId: providerId,
+  target: target,
+  id: jobId,
+  inputDataUri: "https://<input-data-url>",
+  name: jobName,
+  outputDataFormat: outputDataFormat,
+  inputParams: inputParams,
+};
+const createdJob = await quantumJobClient.jobs.create(jobId, createJobDetails);
 ```
 
 ### Get Job
 
 `GetJob` retrieves a specific job by its id.
 
-```Javascript Snippet
-    // Get the job that we've just created based on its jobId
-    const myJob = await quantumJobClient.jobs.get(jobId);
+```ts snippet:ReadmeSampleGetJob
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+
+const credential = new DefaultAzureCredential();
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
+
+// Get the job that we've just created based on its jobId
+const myJob = await quantumJobClient.jobs.get("job-1234");
 ```
 
 ### Get Jobs
 
 To enumerate all the jobs in the workspace, use the `jobs.list` method.
 
-```Javascript Snippet
-    let jobListResult = await quantumJobClient.jobs.list();
-    let listOfJobs = await jobListResult.next();
-    while (!listOfJobs.done) {
-      let job = listOfJobs.value;
-      console.log(`  ${job.name}`);
-      listOfJobs = await jobListResult.next();
-    }
+```ts snippet:ReadmeSampleListJobs
+import { DefaultAzureCredential } from "@azure/identity";
+import { QuantumJobClient } from "@azure/quantum-jobs";
+
+const credential = new DefaultAzureCredential();
+const subscriptionId = "your_subscription_id";
+const resourceGroupName = "your_resource_group_name";
+const workspaceName = "your_quantum_workspace_name";
+const location = "westus";
+const endpoint = `https://${location}.quantum.azure.com`;
+
+const quantumJobClient = new QuantumJobClient(
+  credential,
+  subscriptionId,
+  resourceGroupName,
+  workspaceName,
+  {
+    endpoint: endpoint,
+    credentialScopes: "https://quantum.microsoft.com/.default",
+  },
+);
+
+const jobListResult = quantumJobClient.jobs.list();
+for await (const job of jobListResult) {
+  console.log(`Job Id: ${job.id} and Job Name: ${job.name}`);
+}
 ```
 
 ## Next steps
@@ -224,6 +332,18 @@ additional questions or comments.
 
 All Quantum Jobs service operations will throw a RequestFailedException on failure with helpful ErrorCodes. Many of these errors are recoverable.
 
+### Logging
+
+Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
+
+```ts snippet:SetLogLevel
+import { setLogLevel } from "@azure/logger";
+
+setLogLevel("info");
+```
+
+For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger).
+
 <!-- LINKS -->
 
 [source]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/quantum/quantum-jobs/src