Utilizza l'API IBM Cloud Resource Controller per la gestione delle istanze

È possibile utilizzare l'API REST di IBM Cloud® Resource Controller per recuperare, creare e aggiornare le istanze in modo programmatico.

Tutti gli endpoint Resource Controller richiedono l'autenticazione tramite l'invio di un'intestazione denominata Authorization con il token bearer. Consultare la guida alla configurazione dell'API REST.

Ottieni un'istanza

Utilizza GET /v2/resource_instances/{crn} l'endpoint per ottenere informazioni su una specifica istanza. L'CRN e deve essere codificato con l'URL nel percorso.

Oltre ai campi standard di Resource Controller, la risposta include campi specifici per la meccanica quantistica sia parameters in che in extensions. extensions memorizza i metadati normalizzati dell'istanza, mentre parameters memorizza solo la richiesta più recente di modifica dell'istanza. Pertanto, dovresti leggere da extensions anziché da parameters.

extensions L'oggetto include i seguenti campi:

• instance_limit_seconds — Numero intero, oppure null. Il limite di tempo di utilizzo dell'istanza. VediImpostazione dei limiti di allocazione delle istanze.
• usage_allocation_seconds — Numero intero, oppure null. Il tempo assegnato a questa istanza, utilizzato dallo scheduler fair-share per determinare la priorità nella coda. Vedi Impostazione dei limiti di allocazione delle istanze.
• backends — Array di stringhe. L'elenco dei nomi dei backend autorizzati disponibili per questa istanza. ["ANY"] significa che tutti i backend inclusi nel piano sono disponibili (impostazione predefinita). [] significa che non sono disponibili backend.

curl \
  --request GET \
  --url 'https://resource-controller.cloud.ibm.com/v2/resource_instances/<YOUR_INSTANCE_CRN_URL_ENCODED>' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

import urllib.parse
import requests

crn = "<YOUR_INSTANCE_CRN>"
# We use urllib.parse.quote to URL-encode the CRN.
url = (
    "https://resource-controller.cloud.ibm.com/v2/resource_instances/"
    + urllib.parse.quote(crn, safe="")
)

resp = requests.get(
    url,
    headers={"Authorization": f"Bearer {token}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Ottieni un elenco di tutte le istanze

Utilizza GET /v2/resource_instances l'endpoint per ottenere un elenco di tutte le tue istanze. Imposta il resource_id parametro di query su b6049020-80f4-11eb-a0f7-e35ec9b4054f per filtrare le istanze di IBM Quantum®.

Se il tuo account dispone di più piani e desideri filtrare i risultati in base al piano, imposta il resource_plan_id parametro di query su uno dei seguenti valori:

Ogni risultato include gli stessi extensions campi descritti nella sezione Ottenere un'istanza.

curl \
  --request GET \
  --url 'https://resource-controller.cloud.ibm.com/v2/resource_instances?resource_id=b6049020-80f4-11eb-a0f7-e35ec9b4054f' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

import requests

resp = requests.get(
    "https://resource-controller.cloud.ibm.com/v2/resource_instances?resource_id=b6049020-80f4-11eb-a0f7-e35ec9b4054f",
    headers={"Authorization": f"Bearer {token}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Aggiornare un'istanza

Utilizza l'endpoint PATCH /v2/resource_instances/{crn} per aggiornare il limite, l'allocazione e i backend consentiti per un'istanza. L'CRN e deve essere codificato con l'URL nel percorso.

"Content-Type: application/json" Inserisci nel corpo della richiesta un parameters oggetto JSON contenente i campi che desideri modificare, insieme all'intestazione. I campi omessi rimangono invariati.

• instance_limit_seconds — Numero intero, oppure null. Il limite di tempo di utilizzo dell'istanza. VediImpostazione dei limiti di allocazione delle istanze.
• usage_allocation_seconds — Numero intero, oppure null. Il tempo assegnato a questa istanza, utilizzato dallo scheduler fair-share per determinare la priorità nella coda. Vedi Impostazione dei limiti di allocazione delle istanze . Non applicabile alle istanze Pay-As-You-Go.
• backends — Array di stringhe. L'elenco dei nomi dei backend autorizzati disponibili per questa istanza. ["ANY"] significa che tutti i backend inclusi nel piano sono disponibili. [] significa che non sono disponibili backend.

La risposta dell'endpoint è simile a quella che si ottiene quando si recupera un'istanza, compreso il modo in cui gestisce l'oggetto extensions.

curl \
--request PATCH \
--url 'https://resource-controller.cloud.ibm.com/v2/resource_instances/<YOUR_INSTANCE_CRN_URL_ENCODED>' \
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
--header 'Content-Type: application/json' \
--data "{
    \"parameters\": {
        \"timestamp\": \"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\",
        \"usage_allocation_seconds\": 220
    }
}"

import urllib.parse
import datetime
import requests

crn = "<YOUR_INSTANCE_CRN>"
# We use urllib.parse.quote to URL-encode the CRN.
url = (
    "https://resource-controller.cloud.ibm.com/v2/resource_instances/"
    + urllib.parse.quote(crn, safe="")
)

timestamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
body = {
    "parameters": {
        "timestamp": timestamp,
        "usage_allocation_seconds": 220,
    }
}

resp = requests.patch(
    url,
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json=body,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Crea una nuova istanza

Utilizza POST /v2/resource_instances l'endpoint per creare (provisionare) una nuova istanza. Invia un corpo JSON con l'intestazione "Content-Type: application/json".

Campi obbligatori:

• name — Un nome comprensibile per l'istanza.
• target — La regione, ad esempio us-east o eu-de.
• resource_plan_id — Il piano per questa situazione. Consultare la tabella degli ID dei piani.
• resource_group — Il gruppo di risorse da utilizzare.

È inoltre possibile includere un parameters oggetto per impostare valori specifici di Quantum:

• instance_limit_seconds — Numero intero, oppure null. Il limite di tempo di utilizzo dell'istanza. VediImpostazione dei limiti di allocazione delle istanze.
• usage_allocation_seconds — Numero intero, oppure null. Il tempo assegnato a questa istanza, utilizzato dallo scheduler fair-share per determinare la priorità nella coda. Vedi Impostazione dei limiti di allocazione delle istanze . Non applicabile alle istanze Pay-As-You-Go.
• backends — Array di stringhe. L'elenco dei nomi dei backend autorizzati disponibili per questa istanza. ["ANY"] significa che tutti i backend inclusi nel piano sono disponibili. [] significa che non sono disponibili backend.

curl \
  --request POST \
  --url 'https://resource-controller.cloud.ibm.com/v2/resource_instances' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
      "name": "my-new-instance",
      "target": "us-east",
      "resource_plan_id": "7f666d17-7893-47d8-bf9d-2b2389fc4dfc",
      "resource_group": "<YOUR_RESOURCE_GROUP_ID>",
      "parameters": {
          "instance_limit_seconds": 300,
          "usage_allocation_seconds": 220
      }
  }'

import requests

body = {
    "name": "my-new-instance",
    "target": "us-east",
    "resource_plan_id": "7f666d17-7893-47d8-bf9d-2b2389fc4dfc",
    "resource_group": "<YOUR_RESOURCE_GROUP_ID>",
    "parameters": {
        "instance_limit_seconds": 300,
        "usage_allocation_seconds": 220,
    },
}

resp = requests.post(
    "https://resource-controller.cloud.ibm.com/v2/resource_instances",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json=body,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Configurare l'accesso a Qiskit Functions su un'istanza

Seguire queste istruzioni per configurare l'accesso a Qiskit Functions su un'istanza esistente di IBM Quantum Compute Service utilizzando l'API IBM Cloud Resource Controller. Segui le istruzioni in ordine, poiché i comandi si basano l'uno sull'altro. Ad esempio, variabili come il token e l’ URL e vengono impostate in una fase e riutilizzate nelle fasi successive.

Prerequisiti

• Una chiave API di IBM Cloud (chiamata anche “token”). Se necessario, crea la tua chiave API nella dashboard.
• L' CRN e dell'istanza che si desidera configurare. L' CRN e dell'istanza è riportata nella pagina " Istanze ".

Passaggio 1: Ottenere un token al portatore

Scambia la tua chiave API con un token bearer. Dovrai includere questo token nell'intestazione di autorizzazione di tutte le richieste inviate al controller delle risorse. Esegui il codice seguente per generare un token bearer:

curl --request POST \
--url 'https://iam.cloud.ibm.com/identity/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'apikey=<YOUR_API_KEY>&grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey'
--silent | jq .

import requests

api_key = "<YOUR_API_KEY>"

resp = requests.post(
"https://iam.cloud.ibm.com/identity/token",
headers={"Content-Type": "application/x-www-form-urlencoded"},
params={
    "apikey": api_key,
    "grant_type": "urn:ibm:params:oauth:grant-type:apikey",
},
timeout=30,
)
resp.raise_for_status()
token = resp.json()["access_token"]
print(token) 

La risposta include un access_token campo, che rappresenta il tuo token bearer. Copia questo valore.

Fase 2: Verifica dell'accesso

Prima di apportare qualsiasi modifica, verifica che il tuo token funzioni e controlla la configurazione corrente dell'istanza.

curl --request GET \
--url 'https://resource-controller.cloud.ibm.com/v2/resource_instances/<YOUR_INSTANCE_CRN_URL_ENCODED>' \
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

import urllib.parse

crn = "<YOUR_INSTANCE_CRN>"
# The CRN will be URL-encoded into the path.
instance_url = (
"https://resource-controller.cloud.ibm.com/v2/resource_instances/"
+ urllib.parse.quote(crn, safe="")
)
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

resp = requests.get(instance_url, headers=headers, timeout=30)
resp.raise_for_status()
print(resp.json()["extensions"])

Una risposta 200 OK conferma che il tuo token è valido. La configurazione corrente dell'istanza è riportata nel campo "extensions" della risposta. Utilizza questo al posto dei parametri, che potrebbero non essere aggiornati.

Fase 3: Verificare la configurazione delle funzioni a livello di account

A un'istanza può essere concesso l'accesso solo a ciò a cui l'account ha diritto. Prima di configurare l'istanza, consulta la configurazione dell'account per verificare quali funzioni, modelli di business e autorizzazioni è possibile concedere. Questa è la fonte attendibile dei valori che invierai al Passo 4.

Effettua una chiamata GET /accounts/{id} all'API di Qiskit Runtime utilizzando la tua chiave API. Il {id} è l'ID del tuo account senza il prefisso a/ . È possibile trovarlo nell'istanza CRN (crn:v1:bluemix:public:quantum-computing:...:a/<ACCOUNT_ID>:...).

curl --request GET \
--url 'https://quantum.cloud.ibm.com/api/v1/accounts/<ACCOUNT_ID>' \
--header 'Authorization: apikey <YOUR_API_KEY>'

account_id = "<ACCOUNT_ID>"  # from the CRN: crn:...:a/<ACCOUNT_ID>:...

resp = requests.get(
f"https://quantum.cloud.ibm.com/api/v1/accounts/{account_id}",
headers={"Authorization": f"apikey {api_key}"},
timeout=30,
)
resp.raise_for_status()
for plan in resp.json()["plans"]:
print(plan["plan_id"], plan.get("functions"), plan.get("custom_functions"))

Ogni piano nella risposta include un array di funzioni e, se configurato, un oggetto custom_functions . Qui sono riportati il nome esatto, il fornitore, il modello di business e i valori delle autorizzazioni che è possibile concedere a un'istanza nell'ambito di quel piano.

Fase 4: Configurazione dell'accesso alle funzioni

Aggiorna l'istanza per concedere l'accesso alle funzioni del catalogo e alle funzioni personalizzate.

curl --request PATCH \
--url 'https://resource-controller.cloud.ibm.com/v2/resource_instances/<YOUR_INSTANCE_CRN_URL_ENCODED>' \
--header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"parameters": {
  "timestamp": "2026-06-30T00:00:00Z",
  "functions": [
    {
      "name": "<FUNCTION_NAME>",
      "provider": "<PROVIDER>",
      "business_model": "<BUSINESS_MODEL>",
      "permissions": [
        "function.read",
        "function.run",
        "function-files.read",
        "function-files.write"
      ]
    }
  ],
  "custom_functions": {
    "permissions": [
      "function-custom.write",
      "function-custom.run"
    ]
  }
}
}'

from datetime import datetime, timezone

# A changing timestamp keeps the Resource Controller from de-duplicating the request.
_now = datetime.now(timezone.utc)
timestamp = _now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{_now.microsecond:06d}000Z"

body = {
"parameters": {
    "timestamp": timestamp,
    "functions": [
        {
            "name": "<FUNCTION_NAME>",
            "provider": "<PROVIDER>",
            "business_model": "<BUSINESS_MODEL>",
            "permissions": [
                "function.read",
                "function.run",
                "function-files.read",
                "function-files.write",
            ],
        }
    ],
    "custom_functions": {
        "permissions": ["function-custom.write", "function-custom.run"],
    },
}
}

resp = requests.patch(instance_url, headers=headers, json=body, timeout=30)
resp.raise_for_status()
print(resp.json()["extensions"])

Una risposta 200 OK indica che l'operazione è andata a buon fine. La configurazione aggiornata viene visualizzata nel campo delle estensioni della risposta.

Rimuovi l'accesso alle funzioni

Funzioni del catalogo

Per rimuovere le funzioni del catalogo da un'istanza, inviare un PATCH con "functions": null:

--data '{
"parameters": {
"timestamp": "2026-06-30T00:00:01Z",
"functions": null
}
}'

body = {"parameters": {"timestamp": timestamp, "functions": None}}
resp = requests.patch(instance_url, headers=headers, json=body, timeout=30)
resp.raise_for_status()

L'impostazione di ( "functions": [] un array vuoto) ha l'effetto equivalente a azzerare le funzioni del catalogo. null è la forma canonica.

Personalizzazione delle funzioni

Per rimuovere le funzioni personalizzate da un'istanza, inviare una richiesta PATCH con "custom_functions": null:

--data '{
"parameters": {
"timestamp": "2026-06-30T00:00:02Z",
"custom_functions": null
}
}'

body = {"parameters": {"timestamp": timestamp, "custom_functions": None}}
resp = requests.patch(instance_url, headers=headers, json=body, timeout=30)
resp.raise_for_status()

L'impostazione cancella, in modo equivalente "custom_functions": {"permissions": []} , le funzioni personalizzate. null è la forma canonica.

Verifica il risultato

Per verificare che l'istanza disponga della corretta configurazione di Qiskit Functions, utilizzare GET /functions l'API Qiskit Runtime al posto di Resource Controller. Lo stato memorizzato dell' Resource Controller potrebbe non essere aggiornato se alcune modifiche a livello di account hanno aggiornato l'istanza al di fuori dell' Resource Controller.

curl --request GET \
--url 'https://quantum.cloud.ibm.com/api/v1/functions' \
--header 'Authorization: apikey <YOUR_API_KEY>' \
--header 'Service-CRN: <YOUR_INSTANCE_CRN>'

# The Service-CRN header takes the raw CRN, not the URL-encoded form.
resp = requests.get(
"https://quantum.cloud.ibm.com/api/v1/functions",
headers={"Authorization": f"apikey {api_key}", "Service-CRN": crn},
timeout=30,
)
resp.raise_for_status()
print(resp.json())

La risposta elenca le funzioni a cui l'istanza ha attualmente accesso.