Użyj interfejsu IBM Cloud Resource Controller API do zarządzania instancjami

Możesz użyć interfejsu IBM Cloud® Resource Controller REST API, aby programowo pobierać, tworzyć i aktualizować instancje.

Wszystkie punkty końcowe Resource Controller wymagają uwierzytelnienia poprzez przekazanie nagłówka o nazwie Authorization z tokenem bearer. Zapoznaj się z przewodnikiem konfiguracji REST API.

Pobierz instancję

Użyj punktu końcowego GET /v2/resource_instances/{crn}, aby uzyskać informacje o konkretnej instancji. CRN musi być zakodowany URL-owo w ścieżce.

Oprócz standardowych pól Resource Controller, odpowiedź zawiera pola specyficzne dla kwantowych obliczeń zarówno w parameters, jak i extensions. extensions przechowuje znormalizowane metadane instancji, natomiast parameters przechowuje tylko najnowsze żądanie modyfikacji instancji. Dlatego powinieneś odczytywać dane z extensions, a nie z parameters.

Obiekt extensions zawiera następujące pola:

instance_limit_seconds — liczba całkowita lub null. Limit czasu użytkowania dla instancji. Zobacz Ustawianie limitów alokacji instancji.
usage_allocation_seconds — liczba całkowita lub null. Czas przydzielony dla tej instancji, używany przez harmonogram fair-share do określania priorytetu w kolejce. Zobacz Ustawianie limitów alokacji instancji.
backends — tablica ciągów znaków. Lista dozwolonych nazw Backend'ów dostępnych dla tej instancji. ["ANY"] oznacza, że wszystkie Backend'y w planie są dostępne (wartość domyślna). [] oznacza brak dostępnych Backend'ów.

Pole backends może być nieaktualne

Pole backends w obiekcie extensions może być nieaktualne. Może się to zdarzyć, gdy IBM Quantum Support zmieni Twoje konto w sposób, który wpływa na instancje. Na przykład, gdy Backend zostanie usunięty z konta, zaktualizuje to backends dla instancji, ale ta zmiana nie jest obecnie jeszcze odzwierciedlona w Resource Controller API.

Zamiast tego, aktualnym obejściem jest użycie IBM Quantum Compute Service REST API z punktem końcowym GET /v1/backends. (Upewnij się, że ustawiłeś nagłówek Service-CRN na CRN swojej instancji.)

cURL
Python

CRN musi być zakodowany URL-owo w ścieżce. Zastąp każdy : przez %3A, a każdy / przez %2F. Na przykład crn:v1:bluemix:... staje się 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())

Pobierz listę wszystkich instancji

Użyj punktu końcowego GET /v2/resource_instances, aby uzyskać listę wszystkich Twoich instancji. Ustaw parametr zapytania resource_id na b6049020-80f4-11eb-a0f7-e35ec9b4054f, aby filtrować tylko instancje IBM Quantum®.

Jeśli Twoje konto ma wiele planów i chcesz filtrować według planu, ustaw parametr zapytania resource_plan_id na jedną z następujących wartości:

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`

Każdy wynik zawiera to samo pole extensions, jak opisano w Pobierz instancję.

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

Aktualizuj instancję

Użyj punktu końcowego PATCH /v2/resource_instances/{crn}, aby zaktualizować limit, alokację i dozwolone Backend'y dla instancji. CRN musi być zakodowany URL-owo w ścieżce.

Przekaż obiekt JSON parameters w treści żądania z polami, które chcesz zmienić, wraz z nagłówkiem "Content-Type: application/json". Pominięte pola pozostają niezmienione.

instance_limit_seconds — liczba całkowita lub null. Limit czasu użytkowania dla instancji. Zobacz Ustawianie limitów alokacji instancji.
usage_allocation_seconds — liczba całkowita lub null. Czas przydzielony dla tej instancji, używany przez harmonogram fair-share do określania priorytetu w kolejce. Zobacz Ustawianie limitów alokacji instancji. Nie dotyczy instancji Pay-As-You-Go.
backends — tablica ciągów znaków. Lista dozwolonych nazw Backend'ów dostępnych dla tej instancji. ["ANY"] oznacza, że wszystkie Backend'y w planie są dostępne. [] oznacza brak dostępnych Backend'ów.

Zawsze dołączaj unikalny znacznik czasu

API po cichu ignoruje żądanie, jeśli parameters jest identyczne z poprzednim żądaniem. W obiekcie parameters zawsze dołączaj pole timestamp ustawione na bieżący czas, aby każde żądanie było traktowane jako unikalne.

Odpowiedź tego punktu końcowego jest podobna do pobierania instancji, w tym sposobu obsługi obiektu extensions.

cURL
Python

CRN musi być zakodowany URL-owo w ścieżce. Zastąp każdy : przez %3A, a każdy / przez %2F. Na przykład crn:v1:bluemix:... staje się 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())

Utwórz nową instancję

Użyj punktu końcowego POST /v2/resource_instances, aby utworzyć (dostarczyć) nową instancję. Przekaż treść JSON z nagłówkiem "Content-Type: application/json".

Wymagane pola:

name — czytelna dla człowieka nazwa instancji.
target — region, taki jak us-east lub eu-de.
resource_plan_id — plan dla tej instancji. Zobacz tabelę ID planów.
resource_group — grupa zasobów do użycia.

Możesz również dołączyć obiekt parameters, aby ustawić wartości specyficzne dla kwantowych obliczeń:

instance_limit_seconds — liczba całkowita lub null. Limit czasu użytkowania dla instancji. Zobacz Ustawianie limitów alokacji instancji.
usage_allocation_seconds — liczba całkowita lub null. Czas przydzielony dla tej instancji, używany przez harmonogram fair-share do określania priorytetu w kolejce. Zobacz Ustawianie limitów alokacji instancji. Nie dotyczy instancji Pay-As-You-Go.
backends — tablica ciągów znaków. Lista dozwolonych nazw Backend'ów dostępnych dla tej instancji. ["ANY"] oznacza, że wszystkie Backend'y w planie są dostępne. [] oznacza brak dostępnych Backend'ów.

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

Konfiguruj dostęp do Qiskit Functions na instancji

Użyj tych instrukcji, aby skonfigurować dostęp do Qiskit Functions na istniejącej instancji IBM Quantum Compute Service za pomocą IBM Cloud Resource Controller API. Postępuj zgodnie z instrukcjami w kolejności, ponieważ polecenia opierają się na sobie nawzajem. Na przykład zmienne takie jak token i URL są ustawiane w jednym kroku i ponownie używane w kolejnych krokach.

Wymagania wstępne

Klucz API IBM Cloud (nazywany również tokenem). W razie potrzeby utwórz swój klucz API na pulpicie nawigacyjnym.
CRN instancji, którą chcesz skonfigurować. CRN instancji jest wymieniony na stronie Instances.

Krok 1: Pobierz token bearer

Wymień swój klucz API na token bearer. Będziesz przekazywać ten token w nagłówku autoryzacji wszystkich żądań resource controllera. Uruchom poniższy kod, aby wygenerować 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) 

Odpowiedź zawiera pole access_token, które jest Twoim tokenem bearer. Skopiuj tę wartość.

Krok 2: Zweryfikuj dostęp

Przed wprowadzeniem jakichkolwiek zmian, potwierdź, że Twój token działa i sprawdź bieżącą konfigurację instancji.

cURL
Python

Ważne

CRN musi być ręcznie zakodowany URL-owo w ścieżce. Zastąp każdy : przez %3A, a każdy / przez %2F. Na przykład crn:v1:bluemix:... staje się 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 zostanie zakodowany URL-owo w ścieżce.
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"])

Odpowiedź 200 OK potwierdza, że Twój token jest prawidłowy. Bieżąca konfiguracja instancji znajduje się w polu extensions odpowiedzi. Użyj tego zamiast parameters, które mogą być nieaktualne.

Krok 3: Sprawdź konfigurację funkcji na poziomie konta

Instancji można przyznać dostęp tylko do tego, do czego uprawnione jest konto. Przed skonfigurowaniem instancji, sprawdź konfigurację konta, aby wiedzieć, które funkcje, modele biznesowe i uprawnienia są dostępne do przyznania. Jest to źródło prawdy dla wartości, które wyślesz w kroku 4.

Wywołaj GET /accounts/{id} w Qiskit Runtime API za pomocą swojego klucza API. {id} to identyfikator Twojego konta bez prefiksu a/. Możesz go znaleźć na podstawie CRN instancji (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żdy plan w odpowiedzi zawiera tablicę functions oraz, jeśli jest skonfigurowany, obiekt custom_functions. Zawierają one dokładną nazwę, dostawcę, model biznesowy i wartości uprawnień, które możesz przyznać instancji w ramach tego planu.

uwaga

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: Skonfiguruj dostęp do funkcji

Zaktualizuj instancję, aby przyznać dostęp do Catalog Functions i Custom Functions.

Ważne uwagi

Wartości name, provider i business_model w functions muszą dokładnie odpowiadać wpisom skonfigurowanym na poziomie konta (zobacz poprzedni krok). Permissions musi być niepustym podzbiorem uprawnień konta dla tej funkcji. Podobnie custom_functions.permissions musi być niepustym podzbiorem uprawnień custom_functions konta.
Dołączaj znacznik czasu w parameters przy każdym PATCH. Resource Controller deduplikuje żądania PATCH, porównując przychodzące parameters z ostatnią przechowywaną wartością. Jeśli są zgodne, żądanie jest po cichu odrzucane z kodem 200 OK bez dotarcia do usługi. Dołączaj zmieniającą się wartość znacznika czasu, aby temu zapobiec.

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

# Zmieniający się znacznik czasu zapobiega deduplikacji żądania przez Resource Controller.
_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"])

Odpowiedź 200 OK oznacza sukces. Zaktualizowana konfiguracja pojawia się w polu extensions odpowiedzi.

Usuń dostęp do funkcji

Funkcje z katalogu

Aby usunąć Catalog Functions z instancji, wyślij PATCH z "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()

Ustawienie "functions": [] (pusta tablica) równoważnie usuwa Catalog Functions. null jest formą kanoniczną.

Funkcje niestandardowe

Aby usunąć Custom Functions z instancji, wyślij PATCH z "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()

Ustawienie "custom_functions": {"permissions": []} równoważnie usuwa custom functions. null jest formą kanoniczną.

Zweryfikuj wynik

Aby potwierdzić, że instancja ma prawidłową konfigurację Qiskit Functions, użyj GET /functions z Qiskit Runtime API zamiast Resource Controller. Przechowywany stan Resource Controller może być nieaktualny, jeśli zmiany na poziomie konta zaktualizowały instancję poza 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>'

# Nagłówek Service-CRN przyjmuje surowy CRN, a nie formę zakodowaną URL-owo.
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())

Odpowiedź zawiera listę funkcji, do których instancja obecnie ma dostęp.

Pobierz instancję​

Pobierz listę wszystkich instancji​

Aktualizuj instancję​

Utwórz nową instancję​

Konfiguruj dostęp do Qiskit Functions na instancji​

Wymagania wstępne​

Krok 1: Pobierz token bearer​

Krok 2: Zweryfikuj dostęp​

Krok 3: Sprawdź konfigurację funkcji na poziomie konta​

Krok 4: Skonfiguruj dostęp do funkcji​

Usuń dostęp do funkcji​

Funkcje z katalogu​

Funkcje niestandardowe​

Zweryfikuj wynik​