Folosește API-ul IBM Cloud Resource Controller pentru gestionarea instanțelor

Poți folosi API-ul REST IBM Cloud® Resource Controller pentru a obține, crea și actualiza programatic instanțe.

Toate punctele finale ale Resource Controller necesită să te autentifici prin transmiterea unui header numit Authorization cu tokenul bearer. Consultă ghidul de configurare al API-ului REST.

Obținerea unei instanțe

Folosește punctul final GET /v2/resource_instances/{crn} pentru a obține informații despre o anumită instanță. CRN trebuie să fie codat URL în cale.

Pe lângă câmpurile standard ale Resource Controller, răspunsul include câmpuri specifice cuantice atât în parameters, cât și în extensions. extensions stochează metadatele normalizate ale instanței, în timp ce parameters stochează doar cea mai recentă cerere de modificare a instanței. Prin urmare, ar trebui să citești din extensions și nu din parameters.

Obiectul extensions include aceste câmpuri:

instance_limit_seconds — Integer, sau null. Limita de timp de utilizare pentru instanță. Vezi Setarea limitelor de alocare a instanței.
usage_allocation_seconds — Integer, sau null. Timpul alocat pentru această instanță, folosit de planificatorul fair-share pentru a determina prioritatea în coadă. Vezi Setarea limitelor de alocare a instanței.
backends — Array de string-uri. Lista de permisiuni a numelor de Backend-uri disponibile pentru această instanță. ["ANY"] înseamnă că toate Backend-urile de pe plan sunt disponibile (implicit). [] înseamnă că niciun Backend nu este disponibil.

Câmpul backends poate fi neactualizat

Câmpul backends din obiectul extensions poate fi neactualizat. Acest lucru se poate întâmpla atunci când IBM Quantum Support modifică contul tău într-un mod care afectează instanțele. De exemplu, când un Backend este eliminat dintr-un cont, acesta va actualiza backends pentru instanță, dar acea modificare nu este momentan reflectată în API-ul Resource Controller.

În schimb, soluția temporară actuală este să folosești API-ul REST IBM Quantum Compute Service cu punctul final GET /v1/backends. (Asigură-te că setezi headerul Service-CRN la CRN-ul instanței tale.)

cURL
Python

CRN-ul trebuie să fie codat URL în cale. Înlocuiește fiecare : cu %3A și fiecare / cu %2F. De exemplu, crn:v1:bluemix:... devine 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>"
# 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())

Obținerea unei liste cu toate instanțele

Folosește punctul final GET /v2/resource_instances pentru a obține o listă cu toate instanțele tale. Setează parametrul de interogare resource_id la b6049020-80f4-11eb-a0f7-e35ec9b4054f pentru a filtra doar instanțele IBM Quantum®.

Dacă contul tău are mai multe planuri și dorești să filtrezi după plan, setează parametrul de interogare resource_plan_id la una dintre următoarele valori:

Plan	`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`

Fiecare rezultat include același câmp extensions descris în Obținerea unei instanțe.

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

Actualizarea unei instanțe

Folosește punctul final PATCH /v2/resource_instances/{crn} pentru a actualiza limita, alocarea și Backend-urile permise pentru o instanță. CRN trebuie să fie codat URL în cale.

Trece un obiect JSON parameters în corpul cererii cu câmpurile pe care vrei să le modifici, împreună cu headerul "Content-Type: application/json". Câmpurile omise rămân neschimbate.

instance_limit_seconds — Integer, sau null. Limita de timp de utilizare pentru instanță. Vezi Setarea limitelor de alocare a instanței.
usage_allocation_seconds — Integer, sau null. Timpul alocat pentru această instanță, folosit de planificatorul fair-share pentru a determina prioritatea în coadă. Vezi Setarea limitelor de alocare a instanței. Nu se aplică instanțelor Pay-As-You-Go.
backends — Array de string-uri. Lista de permisiuni a numelor de Backend-uri disponibile pentru această instanță. ["ANY"] înseamnă că toate Backend-urile de pe plan sunt disponibile. [] înseamnă că niciun Backend nu este disponibil.

Include întotdeauna un timestamp unic

API-ul ignoră silențios cererea dacă parameters este identic cu cererea anterioară. În obiectul parameters, include întotdeauna un câmp timestamp setat la ora curentă, astfel încât fiecare cerere să fie tratată ca unică.

Răspunsul punctului final este similar cu obținerea unei instanțe, inclusiv modul în care gestionează obiectul extensions.

cURL
Python

CRN-ul trebuie să fie codat URL în cale. Înlocuiește fiecare : cu %3A și fiecare / cu %2F. De exemplu, crn:v1:bluemix:... devine 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>"
# 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())

Crearea unei instanțe noi

Folosește punctul final POST /v2/resource_instances pentru a crea (aproviziona) o instanță nouă. Transmite un corp JSON cu headerul "Content-Type: application/json".

Câmpuri obligatorii:

name — Un nume ușor de citit pentru instanță.
target — Regiunea, cum ar fi us-east sau eu-de.
resource_plan_id — Planul pentru această instanță. Vezi tabelul cu ID-uri de plan.
resource_group — Grupul de resurse de folosit.

Poți include, de asemenea, un obiect parameters pentru a seta valori specifice cuantice:

instance_limit_seconds — Integer, sau null. Limita de timp de utilizare pentru instanță. Vezi Setarea limitelor de alocare a instanței.
usage_allocation_seconds — Integer, sau null. Timpul alocat pentru această instanță, folosit de planificatorul fair-share pentru a determina prioritatea în coadă. Vezi Setarea limitelor de alocare a instanței. Nu se aplică instanțelor Pay-As-You-Go.
backends — Array de string-uri. Lista de permisiuni a numelor de Backend-uri disponibile pentru această instanță. ["ANY"] înseamnă că toate Backend-urile de pe plan sunt disponibile. [] înseamnă că niciun Backend nu este disponibil.

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

Configurarea accesului la Qiskit Functions pe o instanță

Folosește aceste instrucțiuni pentru a configura accesul la Qiskit Functions pe o instanță IBM Quantum Compute Service existentă, utilizând API-ul IBM Cloud Resource Controller. Urmează instrucțiunile în ordine, deoarece comenzile se bazează una pe cealaltă. De exemplu, variabile precum tokenul și URL-ul sunt setate într-un pas și reutilizate în pașii următori.

Cerințe preliminare

O cheie API IBM Cloud (numită și token). Dacă este necesar, creează-ți cheia API pe dashboard.
CRN-ul instanței pe care vrei să o configurezi. CRN-ul instanței este listat pe pagina ta de Instanțe.

Pasul 1: Obținerea unui token bearer

Schimbă-ți cheia API pe un token bearer. Vei transmite acest token în headerul de autorizare al tuturor cererilor către resource controller. Rulează următorul cod pentru a genera un token bearer:

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) 

Răspunsul include un câmp access_token, care este tokenul tău bearer. Copiază această valoare.

Pasul 2: Verificarea accesului

Înainte de a face orice modificare, confirmă că tokenul tău funcționează și inspectează configurația curentă a instanței.

cURL
Python

Important

CRN-ul trebuie codat URL manual în cale. Înlocuiește fiecare : cu %3A și fiecare / cu %2F. De exemplu, crn:v1:bluemix:... devine 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>"
# CRN-ul va fi codat URL în cale.
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"])

Un răspuns 200 OK confirmă că tokenul tău este valid. Configurația curentă a instanței se află în câmpul extensions al răspunsului. Folosește-l pe acesta în loc de parameters, care ar putea fi neactualizat.

Pasul 3: Consultarea configurației funcțiilor la nivel de cont

O instanță poate primi acces doar la ceea ce contul are dreptul să acceseze. Înainte de a configura instanța, consultă configurația contului pentru a ști ce funcții, modele de afaceri și permisiuni sunt disponibile pentru a fi acordate. Aceasta este sursa de adevăr pentru valorile pe care le vei trimite la Pasul 4.

Apelează GET /accounts/{id} pe API-ul Qiskit Runtime cu cheia ta API. {id} este ID-ul contului tău fără prefixul a/. Îl poți găsi din CRN-ul instanței (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"))

Fiecare plan din răspuns include un array de funcții și, dacă este configurat, un obiect custom_functions. Acestea listează numele exact, furnizorul, modelul de afaceri și valorile de permisiuni pe care le poți acorda unei instanțe din acel plan.

notă

GET /accounts/{id} arată ce poate fi acordat la nivelul contului. GET /functions (vezi Verificarea rezultatului) arată ce a fost deja acordat unei instanțe specifice. Folosește punctul final account pentru a descoperi valorile valide și punctul final functions pentru a confirma rezultatul.

Pasul 4: Configurarea accesului la funcții

Actualizează instanța pentru a acorda acces la Catalog Functions și Custom Functions.

Note importante

Valorile name, provider și business_model din functions trebuie să se potrivească exact cu intrările configurate la nivel de cont (vezi pasul anterior). Permissions trebuie să fie un subset nevid al permisiunilor contului pentru acea funcție. În mod similar, custom_functions.permissions trebuie să fie un subset nevid al permisiunilor custom_functions ale contului.
Include un timestamp în parameters la fiecare PATCH. Resource Controller elimină duplicatele cererilor PATCH comparând parametrii primiți cu ultima valoare stocată. Dacă se potrivesc, cererea este eliminată silențios cu 200 OK fără a ajunge la serviciu. Include o valoare de timestamp în schimbare pentru a preveni acest lucru.

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 în schimbare împiedică Resource Controller să elimine duplicatele cererii.
_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"])

Un răspuns 200 OK indică succes. Configurația actualizată apare în câmpul extensions al răspunsului.

Eliminarea accesului la funcții

Catalog Functions

Pentru a elimina Catalog Functions de la o instanță, trimite un PATCH cu "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()

Setarea "functions": [] (un array gol) elimină echivalent Catalog Functions. null este forma canonică.

Custom Functions

Pentru a elimina Custom Functions de la o instanță, trimite un PATCH cu "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()

Setarea "custom_functions": {"permissions": []} elimină echivalent custom functions. null este forma canonică.

Verificarea rezultatului

Pentru a confirma că instanța are configurația corectă de Qiskit Functions, folosește GET /functions din API-ul Qiskit Runtime în loc de Resource Controller. Starea stocată de Resource Controller ar putea fi neactualizată dacă modificările la nivel de cont au actualizat instanța în afara 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>'

# Headerul Service-CRN preia CRN-ul brut, nu forma codată 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())

Răspunsul listează funcțiile la care instanța are acces în prezent.

Obținerea unei instanțe​

Obținerea unei liste cu toate instanțele​

Actualizarea unei instanțe​

Crearea unei instanțe noi​

Configurarea accesului la Qiskit Functions pe o instanță​

Cerințe preliminare​

Pasul 1: Obținerea unui token bearer​

Pasul 2: Verificarea accesului​

Pasul 3: Consultarea configurației funcțiilor la nivel de cont​

Pasul 4: Configurarea accesului la funcții​

Eliminarea accesului la funcții​

Catalog Functions​

Custom Functions​

Verificarea rezultatului​