Skip to main content
IBM Quantum Platform

IBM Quantum API REST del servizio di elaborazione

L'API REST del servizio di calcolo quantistico " IBM Quantum® " consente di eseguire operazioni sulle unità di elaborazione quantistica (QPU) utilizzando le primitive " IBM Quantum ", un'interfaccia semplificata per l'esecuzione dei circuiti che si avvale di tecniche avanzate di compilazione in fase di esecuzione, soppressione degli errori e mitigazione degli errori, oltre a fornire informazioni sulle istanze e sulle QPU a cui si ha accesso.

Gestire le istanze tramite l'API del Resource Controller di IBM Cloud

Prima di utilizzare l'API REST del servizio di calcolo IBM Quantum, è necessario disporre di un'istanza di Quantum Compute. È possibile creare e gestire le istanze in due modi:

  • Utilizzo dell'interfaccia utente : creare e gestire le istanze tramite l 'interfaccia IBM Quantum Platform. Quando si utilizza l'interfaccia utente, se si seleziona la casella di controllo "Imposta come limite", instance_limit_seconds verrà impostato sullo stesso valore di usage_allocation_seconds.
  • Utilizzo dell'API : automatizza il provisioning e la configurazione delle istanze a livello di programmazione utilizzando l' API " IBM Cloud " Resource Controller (distinta dall'API REST del servizio Compute di IBM Quantum ). Utilizza l'API se devi impostare valori diversi per il limite di allocazione e il limite di utilizzo.

Le sezioni seguenti descrivono l'approccio API per la gestione programmatica delle istanze, compresa l'impostazione dei limiti di allocazione e l'accesso al backend.

Parametri di istanza

Quando si crea o si aggiorna un'istanza di Quantum Compute tramite l'API IBM Cloud Resource Controller, è possibile configurare i seguenti parametri nel corpo della richiesta:

  • instance_limit_seconds (facoltativo): il limite da impostare sull'istanza (stringa o null). Per Open Plan, se non specificato, il valore predefinito è 10 minuti.
  • usage_allocation_seconds: Tempo assegnato all'istanza (stringa o null), utilizzato dallo scheduler fair-share per determinare la priorità della coda in base all'utilizzo di tutte le QPU. Non si applica alle istanze Pay-As-You-Go.
  • backends: Array dei nomi dei backend disponibili per questa istanza (array di stringhe o ["ANY"]). L'impostazione predefinita è ["ANY"] (tutti i backend disponibili nel piano). Utilizzare [] se non sono presenti backend.

Estensioni delle istanze

Quando si recuperano i dettagli di un'istanza tramite l'API del Resource Controller di IBM Cloud, la risposta include una extensions proprietà contenente ulteriori informazioni sull'istanza:

  • instance_limit_seconds: Il limite di tempo impostato per l'istanza (numero intero o null, ≥ 0)
  • usage_allocation_seconds: Tempo assegnato all'istanza (numero intero o null, ≥ 0)
  • backends: L'elenco dei nomi dei backend disponibili per questa istanza (array obbligatorio)

Per informazioni complete sui parametri e sulle estensioni, inclusi esempi e endpoint API, consultare la guida "Utilizzo delle API della piattaforma IBM Cloud per accedere alle istanze ".

Utilizza l'API REST del servizio di elaborazione " IBM Quantum "

Le sezioni seguenti descrivono come utilizzare l'API REST del servizio di calcolo di IBM Quantum per inviare lavori e gestire le sessioni. Queste operazioni richiedono l'autenticazione e un'istanza già esistente.

Autenticazione

È necessario fornire un token di portatore IBM Cloud Identity and Access Management (IAM) con ogni chiamata come intestazione http. È possibile generarlo utilizzando la propria chiave API dalla Dashboard, vicino alla parte superiore per un facile accesso. Per ulteriori informazioni sui token bearer, consultare l' API IAM Identity Services. Per generarne uno utilizzando l'API REST di IAM, è possibile utilizzare la seguente richiesta curl.

curl -X POST 'https://iam.cloud.ibm.com/identity/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=MY_APIKEY'

Risposta attesa

{
   "access_token": "<NEW_BEARER_TOKEN>",
   "refresh_token": "not_supported",
   "token_type": "Bearer",
   "expires_in": 3600,
   "expiration": 1473188353,
   "scope": "ibm_openid"
}
Che cos'è un gettone al portatore?

Un token al portatore è una credenziale temporanea che scade dopo non più di un'ora. Dopo la scadenza del token acquisito, è necessario generarne uno nuovo per continuare a chiamare IBM Cloud o altre API di servizio. È possibile eseguire solo le azioni consentite dal livello di accesso assegnato all'interno di tutti gli account.

Utilizzare la proprietà expires_in nella risposta dell'API per identificare la durata della validità del token di accesso specifico.

Inoltre, molte richieste all'API REST richiedono il Cloud Resource Name (CRN) di un'istanza nell'intestazione della richiesta. È possibile vedere le istanze a cui si ha accesso nella dashboard o selezionando la pagina Istanze nel menu in alto a sinistra. Ogni istanza è elencata con il suo identificativo CRN.

Quindi, inviate il vostro token del portatore, il CRN e IBM -API-Version su ogni richiesta all'interno di un'intestazione Authorization e Service-CRN con questo formato:

Authorization: Bearer <YOUR_BEARER_TOKEN>
Service-CRN: <YOUR_INSTANCE_CRN>
IBM-API-Version: <YYYY-MM-DD>

Richiesta di esempio:

regione eu-de

Se l'istanza si trova nella regione eu-de, utilizzare invece questo URL: https://eu-de.quantum.cloud.ibm.com/api/v1/backends

curl -X 'GET' \
    'https://quantum.cloud.ibm.com/api/v1/backends' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
    -H 'IBM-API-Version: 2026-04-15'

Inviare un job

Quando si invia un lavoro, tenere presente quanto segue:

  • Utilizzare l' operazione di creazione del lavoro per inviare lavori primitivi.
  • È possibile inviare più circuiti in un singolo lavoro come un array di OpenQASM stringhe che rappresentano questi circuiti.
  • Specificare la primitiva che si desidera utilizzare con il parametro program_id . I valori primitivi disponibili sono sampler e estimator.
  • Quando si invia un lavoro a una QPU, è necessario specificare il CRN dell'istanza IBM Cloud.
  • Per un elenco dei nomi dei backend che è possibile specificare, consultare i backend a cui si ha accesso nella sezione Risorse di calcolo di IBM Quantum Platform.

Richiesta di esempio per la creazione di un lavoro di stima con un circuito e un osservabile:

regione eu-de

Se l'istanza si trova nella regione eu-de, utilizzare invece questo URL: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs

curl -X 'POST' \
  'https://quantum.cloud.ibm.com/api/v1/jobs' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
  -H 'IBM-API-Version: 2026-04-15' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "program_id": "estimator",
  "backend": "ibm_brisbane",
  "params": {
    "pubs": [[
      "OPENQASM 3.0; include \"stdgates.inc\"; bit[1] c; x $0; c[0] = measure $0;", "Z"
    ]],
    "options": {"dynamical_decoupling": {"enable": true}},
    "version": 2,
    "resilience_level": 1
  }
}'

Utilizza le sessioni

Per avviare una sessione, utilizzare l' operazione Crea sessione. La risposta fornisce un "id" che si può inviare con i lavori per eseguirli come parte della sessione.

L'esempio successivo crea una sessione (senza specificare la modalità):

regione eu-de

Se l'istanza si trova nella regione eu-de, utilizzare invece questo URL: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions

curl -X POST \
  'https://quantum.cloud.ibm.com/api/v1/sessions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
  -H 'IBM-API-Version: 2026-04-15' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "mode": "dedicated",
  "max_ttl": 28800
}'

Otterrete una risposta di questo tipo:

{
  "id": "session_id1"
}

Nel prossimo lavoro, utilizzare l'id di sessione per eseguire questo lavoro come parte della sessione:

regione eu-de

Se l'istanza si trova nella regione eu-de, utilizzare invece questo URL: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs

curl -X POST \
  'https://quantum.cloud.ibm.com/api/v1/jobs' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
  -H 'IBM-API-Version: 2026-04-15' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "program_id": "sampler",
  "backend": "ibm_brisbane",
  "session_id": "session_id1",
  "params": {
    "pubs": [[
      "OPENQASM 3.0; include \"stdgates.inc\"; bit[1] c; x $0; c[0] = measure $0;"
    ]],
    "options": {},
    "version": 2
  }
}'
Questa pagina è stata utile?
Segnala un bug, un errore di battitura o richiedi contenuti su GitHub.