Použití IBM Cloud Resource Controller API pro správu instancí

Můžeš použít IBM Cloud® Resource Controller REST API k programovému získávání, vytváření a aktualizaci instancí.

Všechny koncové body Resource Controller vyžadují, abys se autentizoval/a předáním hlavičky nazvané Authorization s bearer tokenem. Podívej se na průvodce nastavením REST API.

Získání instance

Použij koncový bod GET /v2/resource_instances/{crn} k získání informací o konkrétní instanci. CRN musí být v cestě zakódováno pomocí URL kódování.

Kromě standardních polí Resource Controller odpověď obsahuje pole specifická pro kvantové výpočty jak v parameters, tak v extensions. extensions uchovává normalizovaná metadata instance, zatímco parameters uchovává pouze poslední požadavek na úpravu instance. Proto bys měl/a číst z extensions, nikoli z parameters.

Objekt extensions obsahuje tato pole:

instance_limit_seconds — Celé číslo nebo null. Časový limit využití pro instanci. Viz Nastavení limitů přidělení instance.
usage_allocation_seconds — Celé číslo nebo null. Čas přidělený této instanci, který používá plánovač fair-share k určení priority ve frontě. Viz Nastavení limitů přidělení instance.
backends — Pole řetězců. Seznam povolených názvů Backend dostupných pro tuto instanci. ["ANY"] znamená, že jsou dostupné všechny Backend v rámci plánu (výchozí hodnota). [] znamená, že nejsou dostupné žádné Backend.

Pole backends může být neaktuální

Pole backends v objektu extensions může být neaktuální. To se může stát, když IBM Quantum Support změní tvůj účet způsobem, který ovlivňuje instance. Například když je Backend z účtu odebrán, aktualizuje se backends pro danou instanci, ale tato změna se v současnosti ještě neprojevuje v Resource Controller API.

Místo toho aktuální řešení spočívá v použití IBM Quantum Compute Service REST API s koncovým bodem GET /v1/backends. (Ujisti se, že jsi nastavil/a hlavičku Service-CRN na CRN tvé instance.)

cURL
Python

CRN musí být v cestě zakódováno pomocí URL kódování. Nahraď každé : za %3A a každé / za %2F. Například crn:v1:bluemix:... se stane 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>"
# Používáme urllib.parse.quote k URL kódování 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())

Získání seznamu všech instancí

Použij koncový bod GET /v2/resource_instances k získání seznamu všech tvých instancí. Nastav parametr dotazu resource_id na b6049020-80f4-11eb-a0f7-e35ec9b4054f, abys filtroval/a pouze instance IBM Quantum®.

Pokud má tvůj účet více plánů a chceš filtrovat podle plánu, nastav parametr dotazu resource_plan_id na jednu z následujících hodnot:

Plán	`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`

Každý výsledek obsahuje stejné pole extensions, jak je popsáno v Získání instance.

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

Aktualizace instance

Použij koncový bod PATCH /v2/resource_instances/{crn} k aktualizaci limitu, přidělení a povolených Backend pro instanci. CRN musí být v cestě zakódováno pomocí URL kódování.

Předej JSON objekt parameters v těle požadavku s poli, která chceš změnit, spolu s hlavičkou "Content-Type: application/json". Vynechaná pole zůstanou nezměněna.

instance_limit_seconds — Celé číslo nebo null. Časový limit využití pro instanci. Viz Nastavení limitů přidělení instance.
usage_allocation_seconds — Celé číslo nebo null. Čas přidělený této instanci, který používá plánovač fair-share k určení priority ve frontě. Viz Nastavení limitů přidělení instance. Neplatí pro instance Pay-As-You-Go.
backends — Pole řetězců. Seznam povolených názvů Backend dostupných pro tuto instanci. ["ANY"] znamená, že jsou dostupné všechny Backend v rámci plánu. [] znamená, že nejsou dostupné žádné Backend.

Vždy zahrň jedinečné časové razítko

API tiše ignoruje požadavek, pokud je parameters shodné s předchozím požadavkem. V objektu parameters vždy zahrň pole timestamp nastavené na aktuální čas, aby byl každý požadavek považován za jedinečný.

Odpověď koncového bodu je podobná jako u získání instance, včetně způsobu, jak zachází s objektem extensions.

cURL
Python

CRN musí být v cestě zakódováno pomocí URL kódování. Nahraď každé : za %3A a každé / za %2F. Například crn:v1:bluemix:... se stane 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>"
# Používáme urllib.parse.quote k URL kódování 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())

Vytvoření nové instance

Použij koncový bod POST /v2/resource_instances k vytvoření (poskytnutí) nové instance. Předej JSON tělo s hlavičkou "Content-Type: application/json".

Povinná pole:

name — Čitelný název instance.
target — Region, například us-east nebo eu-de.
resource_plan_id — Plán pro tuto instanci. Viz tabulka ID plánů.
resource_group — Skupina prostředků, kterou chceš použít.

Můžeš také zahrnout objekt parameters k nastavení hodnot specifických pro kvantové výpočty:

instance_limit_seconds — Celé číslo nebo null. Časový limit využití pro instanci. Viz Nastavení limitů přidělení instance.
usage_allocation_seconds — Celé číslo nebo null. Čas přidělený této instanci, který používá plánovač fair-share k určení priority ve frontě. Viz Nastavení limitů přidělení instance. Neplatí pro instance Pay-As-You-Go.
backends — Pole řetězců. Seznam povolených názvů Backend dostupných pro tuto instanci. ["ANY"] znamená, že jsou dostupné všechny Backend v rámci plánu. [] znamená, že nejsou dostupné žádné Backend.

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

Konfigurace přístupu Qiskit Functions na instanci

Použij tyto pokyny ke konfiguraci přístupu Qiskit Functions na existující instanci IBM Quantum Compute Service pomocí IBM Cloud Resource Controller API. Postupuj podle pokynů v pořadí, protože příkazy na sebe navazují. Například proměnné jako token a URL se nastaví v jednom kroku a znovu se použijí v pozdějších krocích.

Požadavky

Klíč API IBM Cloud (nazývaný také token). V případě potřeby si vytvoř klíč API na dashboardu.
CRN instance, kterou chceš konfigurovat. CRN instance je uveden na stránce Instances.

Krok 1: Získání bearer tokenu

Vyměň svůj klíč API za bearer token. Tento token předáš v autorizační hlavičce všech požadavků resource controller. Spusť následující kód k vygenerování bearer tokenu:

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) 

Odpověď obsahuje pole access_token, což je tvůj bearer token. Zkopíruj tuto hodnotu.

Krok 2: Ověření přístupu

Před provedením jakýchkoli změn ověř, že tvůj token funguje, a zkontroluj aktuální konfiguraci instance.

cURL
Python

Důležité

CRN musí být v cestě ručně zakódováno pomocí URL kódování. Nahraď každé : za %3A a každé / za %2F. Například crn:v1:bluemix:... se stane 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 bude v cestě zakódováno pomocí URL kódování.
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"])

Odpověď 200 OK potvrzuje, že tvůj token je platný. Aktuální konfigurace instance je v poli extensions odpovědi. Použij toto pole místo parameters, které může být zastaralé.

Krok 3: Vyhledání konfigurace funkcí na úrovni účtu

Instanci lze udělit přístup pouze k tomu, na co má účet nárok. Před konfigurací instance vyhledej konfiguraci účtu, abys věděl/a, které funkce, obchodní modely a oprávnění lze udělit. Toto je zdroj pravdy pro hodnoty, které pošleš v kroku 4.

Zavolej GET /accounts/{id} na Qiskit Runtime API s tvým klíčem API. {id} je ID tvého účtu bez předpony a/. Můžeš ho najít z CRN instance (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"))

Každý plán v odpovědi obsahuje pole functions a, pokud je nakonfigurován, objekt custom_functions. Ty uvádějí přesný název, poskytovatele, obchodní model a hodnoty oprávnění, které lze udělit instanci v rámci daného plánu.

poznámka

GET /accounts/{id} shows what is available to grant at the account level. GET /functions (see Verify the result) shows what a specific instance has already been granted. Use the account endpoint to discover valid values, and the functions endpoint to confirm the result.

Krok 4: Konfigurace přístupu k funkcím

Aktualizuj instanci, abys udělil/a přístup ke Catalog Functions a Custom Functions.

Důležité poznámky

Hodnoty name, provider a business_model ve functions musí přesně odpovídat záznamům nakonfigurovaným na úrovni účtu (viz předchozí krok). Permissions musí být neprázdnou podmnožinou oprávnění účtu pro danou funkci. Podobně custom_functions.permissions musí být neprázdnou podmnožinou oprávnění custom_functions účtu.
Zahrň do parameters u každého PATCH časové razítko. Resource Controller deduplikuje požadavky PATCH porovnáním příchozích parameters s poslední uloženou hodnotou. Pokud se shodují, požadavek je tiše zahozen s 200 OK, aniž by se dostal ke službě. Zahrň měnící se hodnotu časového razítka, abys tomu předešel/a.

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

# Měnící se časové razítko brání Resource Controller v deduplikaci požadavku.
_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"])

Odpověď 200 OK značí úspěch. Aktualizovaná konfigurace se objeví v poli extensions odpovědi.

Odebrání přístupu k funkcím

Katalogové funkce

Chceš-li odebrat Catalog Functions z instance, odešli PATCH s "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()

Nastavení "functions": [] (prázdné pole) rovnocenně vymaže Catalog Functions. null je kanonická forma.

Vlastní funkce

Chceš-li odebrat Custom Functions z instance, odešli PATCH s "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()

Nastavení "custom_functions": {"permissions": []} rovnocenně vymaže custom functions. null je kanonická forma.

Ověření výsledku

Chceš-li potvrdit, že instance má správnou konfiguraci Qiskit Functions, použij GET /functions z Qiskit Runtime API místo Resource Controller. Uložený stav Resource Controller může být zastaralý, pokud změny na úrovni účtu aktualizovaly instanci mimo 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>'

# Hlavička Service-CRN používá nezakódované CRN, nikoli formu zakódovanou pomocí URL kódování.
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())

Odpověď uvádí seznam funkcí, ke kterým má instance aktuálně přístup.

Získání instance​

Získání seznamu všech instancí​

Aktualizace instance​

Vytvoření nové instance​

Konfigurace přístupu Qiskit Functions na instanci​

Požadavky​

Krok 1: Získání bearer tokenu​

Krok 2: Ověření přístupu​

Krok 3: Vyhledání konfigurace funkcí na úrovni účtu​

Krok 4: Konfigurace přístupu k funkcím​

Odebrání přístupu k funkcím​

Katalogové funkce​

Vlastní funkce​

Ověření výsledku​