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

Puoi utilizzare l'API REST IBM Cloud® Resource Controller per ottenere, creare e aggiornare istanze in modo programmatico.

Tutti gli endpoint di Resource Controller richiedono che tu ti autentichi passando un'intestazione chiamata Authorization con il bearer token. Fai riferimento alla guida di configurazione dell'API REST.

Ottenere un'istanza

Usa l'endpoint GET /v2/resource_instances/{crn} per ottenere informazioni su una particolare istanza. Il CRN deve essere codificato per URL nel percorso.

Oltre ai campi standard di Resource Controller, la risposta include campi specifici per il quantum sia in parameters 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 piuttosto che da parameters.

L'oggetto extensions include questi campi:

instance_limit_seconds — Intero, o null. Il limite di tempo di utilizzo per l'istanza. Vedi Impostare i limiti di allocazione dell'istanza.
usage_allocation_seconds — Intero, o null. Il tempo allocato per questa istanza, utilizzato dallo scheduler fair-share per determinare la priorità nella coda. Vedi Impostare i limiti di allocazione dell'istanza.
backends — Array di stringhe. L'elenco consentito dei nomi di backend disponibili per questa istanza. ["ANY"] significa che tutti i backend del piano sono disponibili (valore predefinito). [] significa che nessun backend è disponibile.

Il campo backends potrebbe non essere aggiornato

Il campo backends nell'oggetto extensions potrebbe non essere aggiornato. Questo può accadere quando IBM Quantum Support modifica il tuo account in un modo che influisce sulle istanze. Ad esempio, quando un backend viene rimosso da un account, verrà aggiornato il campo backends per l'istanza, ma questa modifica attualmente non è ancora riflessa nell'API di Resource Controller.

Al contrario, la soluzione alternativa attuale è utilizzare l'API REST IBM Quantum Compute Service con l'endpoint GET /v1/backends. (Assicurati di impostare l'intestazione Service-CRN sul CRN della tua istanza.)

cURL
Python

Il CRN deve essere codificato per URL nel percorso. Sostituisci ogni : con %3A e ogni / con %2F. Ad esempio, crn:v1:bluemix:... diventa crn%3Av1%3Abluemix%3A....

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>"
# Usiamo urllib.parse.quote per codificare il CRN per URL.
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())

Ottenere un elenco di tutte le istanze

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

Se il tuo account ha più piani e vuoi filtrare per piano, imposta il parametro di query resource_plan_id su uno dei seguenti valori:

Piano	`resource_plan_id`
Premium	`7f666d17-7893-47d8-bf9d-2b2389fc4dfc`
Flex	`53bde9d3-cdbb-46f5-a98f-60ebcadf7260`
Pay-As-You-Go	`5304b575-3cff-4455-90dc-ae4367762093`
Open	`850b21a7-71de-4e53-9441-1abdd202f35d`

Ogni risultato include lo stesso campo extensions descritto in Ottenere un'istanza.

cURL
Python

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

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

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

instance_limit_seconds — Intero, o null. Il limite di tempo di utilizzo per l'istanza. Vedi Impostare i limiti di allocazione dell'istanza.
usage_allocation_seconds — Intero, o null. Il tempo allocato per questa istanza, utilizzato dallo scheduler fair-share per determinare la priorità nella coda. Vedi Impostare i limiti di allocazione dell'istanza. Non applicabile alle istanze Pay-As-You-Go.
backends — Array di stringhe. L'elenco consentito dei nomi di backend disponibili per questa istanza. ["ANY"] significa che tutti i backend del piano sono disponibili. [] significa che nessun backend è disponibile.

Includi sempre un timestamp univoco

L'API ignora silenziosamente la richiesta se parameters è identico alla richiesta precedente. Nell'oggetto parameters, includi sempre un campo timestamp impostato sull'ora corrente in modo che ogni richiesta sia trattata come univoca.

La risposta dell'endpoint è simile a ottenere un'istanza, incluso il modo in cui gestisce l'oggetto extensions.

cURL
Python

Il CRN deve essere codificato per URL nel percorso. Sostituisci ogni : con %3A e ogni / con %2F. Ad esempio, crn:v1:bluemix:... diventa crn%3Av1%3Abluemix%3A....

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>"
# Usiamo urllib.parse.quote per codificare il CRN per URL.
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())

Creare una nuova istanza

Usa l'endpoint POST /v2/resource_instances per creare (effettuare il provisioning di) una nuova istanza. Passa un corpo JSON con l'intestazione "Content-Type: application/json".

Campi obbligatori:

name — Un nome leggibile dall'uomo per l'istanza.
target — La regione, ad esempio us-east o eu-de.
resource_plan_id — Il piano per questa istanza. Vedi la tabella degli ID piano.
resource_group — Il gruppo di risorse da utilizzare.

Puoi anche includere un oggetto parameters per impostare valori specifici per il quantum:

instance_limit_seconds — Intero, o null. Il limite di tempo di utilizzo per l'istanza. Vedi Impostare i limiti di allocazione dell'istanza.
usage_allocation_seconds — Intero, o null. Il tempo allocato per questa istanza, utilizzato dallo scheduler fair-share per determinare la priorità nella coda. Vedi Impostare i limiti di allocazione dell'istanza. Non applicabile alle istanze Pay-As-You-Go.
backends — Array di stringhe. L'elenco consentito dei nomi di backend disponibili per questa istanza. ["ANY"] significa che tutti i backend del piano sono disponibili. [] significa che nessun backend è disponibile.

cURL
Python

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

Usa queste istruzioni per configurare l'accesso a Qiskit Functions su un'istanza IBM Quantum Compute Service esistente 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 vengono impostate in un passaggio e riutilizzate nei passaggi successivi.

Prerequisiti

Una chiave API IBM Cloud (chiamata anche token). Se necessario, crea la tua chiave API sulla dashboard.
Il CRN dell'istanza che vuoi configurare. Il CRN dell'istanza è elencato nella tua pagina Instances.

Passaggio 1: ottenere un bearer token

Scambia la tua chiave API con un bearer token. Passerai questo token nell'intestazione di autorizzazione di tutte le richieste a Resource Controller. Esegui il seguente codice per generare un bearer token:

cURL
Python

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 campo access_token, che è il tuo bearer token. Copia questo valore.

Passaggio 2: verificare l'accesso

Prima di apportare modifiche, conferma che il tuo token funzioni e ispeziona la configurazione attuale dell'istanza.

cURL
Python

Importante

Il CRN deve essere codificato manualmente per URL nel percorso. Sostituisci ogni : con %3A e ogni / con %2F. Ad esempio, crn:v1:bluemix:... diventa crn%3Av1%3Abluemix%3A....

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>"
# Il CRN verrà codificato per URL nel percorso.
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 attuale dell'istanza si trova nel campo extensions della risposta. Usa questo campo invece di parameters, che potrebbe non essere aggiornato.

Passaggio 3: cercare 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, cerca la configurazione dell'account in modo da sapere quali funzioni, modelli di business e permessi sono disponibili da concedere. Questa è la fonte autorevole per i valori che invierai nel Passaggio 4.

Chiama GET /accounts/{id} sull'API Qiskit Runtime con la tua chiave API. {id} è l'ID del tuo account senza il prefisso a/. Puoi trovarlo dal CRN dell'istanza (crn:v1:bluemix:public:quantum-computing:...:a/<ACCOUNT_ID>:...).

cURL
Python

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 functions e, se configurato, un oggetto custom_functions. Questi elencano il nome esatto, il provider, il modello di business e i valori dei permessi che puoi concedere a un'istanza in quel piano.

nota

GET /accounts/{id} mostra cosa è possibile concedere a livello di account. GET /functions (vedi Verificare il risultato) mostra cosa è già stato concesso a un'istanza specifica. Usa l'endpoint account per scoprire i valori validi e l'endpoint functions per confermare il risultato.

Passaggio 4: configurare l'accesso alle funzioni

Aggiorna l'istanza per concedere l'accesso a Catalog Functions e Custom Functions.

Note importanti

I valori name, provider e business_model nelle functions devono corrispondere esattamente alle voci configurate a livello di account (vedi il passaggio precedente). I permessi devono essere un sottoinsieme non vuoto dei permessi dell'account per quella funzione. Analogamente, custom_functions.permissions deve essere un sottoinsieme non vuoto dei permessi custom_functions dell'account.
Includi un timestamp in parameters a ogni PATCH. Resource Controller deduplica le richieste PATCH confrontando i parameters in arrivo con l'ultimo valore memorizzato. Se corrispondono, la richiesta viene scartata silenziosamente con 200 OK senza raggiungere il servizio. Includi un valore di timestamp mutevole per evitarlo.

cURL
Python

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

# Un timestamp mutevole impedisce a Resource Controller di deduplicare la richiesta.
_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 il successo. La configurazione aggiornata appare nel campo extensions della risposta.

Rimuovere l'accesso alle funzioni

Catalog Functions

Per rimuovere Catalog Functions da un'istanza, invia una PATCH con "functions": null:

cURL
Python

--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()

Impostare "functions": [] (un array vuoto) cancella in modo equivalente Catalog Functions. null è la forma canonica.

Custom Functions

Per rimuovere Custom Functions da un'istanza, invia una PATCH con "custom_functions": null:

cURL
Python

--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()

Impostare "custom_functions": {"permissions": []} cancella in modo equivalente le custom functions. null è la forma canonica.

Verificare il risultato

Per confermare che l'istanza abbia la configurazione corretta di Qiskit Functions, usa GET /functions dall'API Qiskit Runtime invece di Resource Controller. Lo stato memorizzato di Resource Controller potrebbe non essere aggiornato se modifiche a livello di account hanno aggiornato l'istanza al di fuori di Resource Controller.

cURL
Python

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

# L'intestazione Service-CRN richiede il CRN grezzo, non la forma codificata per URL.
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.

Ottenere un'istanza​

Ottenere un elenco di tutte le istanze​

Aggiornare un'istanza​

Creare una nuova istanza​

Configurare l'accesso a Qiskit Functions su un'istanza​

Prerequisiti​

Passaggio 1: ottenere un bearer token​

Passaggio 2: verificare l'accesso​

Passaggio 3: cercare la configurazione delle funzioni a livello di account​

Passaggio 4: configurare l'accesso alle funzioni​

Rimuovere l'accesso alle funzioni​

Catalog Functions​

Custom Functions​

Verificare il risultato​