IBM Cloud Resource Controller API für die Instanzverwaltung verwenden

Du kannst die IBM Cloud® Resource Controller REST API verwenden, um Instanzen programmgesteuert abzurufen, zu erstellen und zu aktualisieren.

Für alle Resource Controller-Endpunkte ist eine Authentifizierung erforderlich. Übergib dazu einen Header namens Authorization mit dem Bearer-Token. Weitere Informationen findest du im Leitfaden zur Einrichtung der REST-API.

Eine Instanz abrufen

Verwende den Endpunkt GET /v2/resource_instances/{crn}, um Informationen zu einer bestimmten Instanz abzurufen. Die CRN muss im Pfad URL-codiert sein.

Zusätzlich zu den Standardfeldern des Resource Controllers enthält die Antwort quantenspezifische Felder sowohl in parameters als auch in extensions. extensions speichert die normalisierten Metadaten der Instanz, während parameters nur die letzte Anfrage zur Änderung der Instanz speichert. Daher solltest du aus extensions und nicht aus parameters lesen.

Das Objekt extensions enthält die folgenden Felder:

• instance_limit_seconds — Integer oder null. Das Nutzungszeitlimit für die Instanz. Siehe Zuteilungslimits für Instanzen festlegen.

• usage_allocation_seconds — Integer oder null. Die dieser Instanz zugewiesene Zeit, die vom Fair-Share-Scheduler genutzt wird, um die Priorität in der Warteschlange zu bestimmen. Siehe Zuteilungslimits für Instanzen festlegen.

• backends — Array von Strings. Die Erlaubnisliste der Backend-Namen, die für diese Instanz verfügbar sind. ["ANY"] bedeutet, dass alle Backends des Plans verfügbar sind (Standard). [] bedeutet, dass keine Backends verfügbar sind.

Das Feld „backends“ ist möglicherweise veraltet

Das Feld backends im Objekt extensions ist möglicherweise veraltet. Dies kann passieren, wenn der IBM Quantum-Support dein Konto so ändert, dass sich dies auf Instanzen auswirkt. Wenn beispielsweise ein Backend aus einem Konto entfernt wird, werden die backends für die Instanz aktualisiert, diese Änderung wird jedoch derzeit noch nicht in der Resource Controller API berücksichtigt.

Der aktuelle Workaround besteht stattdessen darin, die IBM Quantum Compute Service REST API mit dem Endpunkt GET /v1/backends zu verwenden. (Stelle sicher, dass du den Header Service-CRN auf die CRN deiner Instanz setzt.)

cURL

Die CRN muss im Pfad URL-codiert sein. Ersetze jeden : durch %3A und jeden / durch %2F. Zum Beispiel wird crn:v1:bluemix:... zu 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>'

Python

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

Eine Liste aller Instanzen abrufen

Verwende den Endpunkt GET /v2/resource_instances, um eine Liste aller deiner Instanzen abzurufen. Setze den Abfrageparameter resource_id auf b6049020-80f4-11eb-a0f7-e35ec9b4054f, um nach IBM Quantum®-Instanzen zu filtern.

Wenn dein Konto mehrere Pläne umfasst und du nach Plan filtern möchtest, setze den Abfrageparameter resource_plan_id auf einen der folgenden Werte:

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

Jedes Ergebnis enthält dasselbe Feld extensions, wie unter Eine Instanz abrufen beschrieben.

cURL

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>'

Python

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

Eine Instanz aktualisieren

Verwende den Endpunkt PATCH /v2/resource_instances/{crn}, um das Limit, die Zuteilung und die zulässigen Backends einer Instanz zu aktualisieren. Die CRN muss im Pfad URL-codiert sein.

Übergib im Anfragetext ein JSON-Objekt parameters mit den Feldern, die du ändern möchtest, zusammen mit dem Header "Content-Type: application/json". Ausgelassene Felder bleiben unverändert.

• instance_limit_seconds — Integer oder null. Das Nutzungszeitlimit für die Instanz. Siehe Zuteilungslimits für Instanzen festlegen.

• usage_allocation_seconds — Integer oder null. Die dieser Instanz zugewiesene Zeit, die vom Fair-Share-Scheduler genutzt wird, um die Priorität in der Warteschlange zu bestimmen. Siehe Zuteilungslimits für Instanzen festlegen. Gilt nicht für Pay-As-You-Go-Instanzen.

• backends — Array von Strings. Die Erlaubnisliste der Backend-Namen, die für diese Instanz verfügbar sind. ["ANY"] bedeutet, dass alle Backends des Plans verfügbar sind. [] bedeutet, dass keine Backends verfügbar sind.

Gib immer einen eindeutigen Zeitstempel an

Die API ignoriert die Anfrage stillschweigend, wenn parameters mit der vorherigen Anfrage identisch ist. Füge im Objekt parameters immer ein Feld timestamp hinzu, das auf die aktuelle Zeit gesetzt ist, damit jede Anfrage als eindeutig behandelt wird.

Die Antwort des Endpunkts ähnelt der beim Abrufen einer Instanz, einschließlich der Behandlung des Objekts extensions.

cURL

Die CRN muss im Pfad URL-codiert sein. Ersetze jeden : durch %3A und jeden / durch %2F. Zum Beispiel wird crn:v1:bluemix:... zu 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
    }
}"

Python

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

Eine neue Instanz erstellen

Verwende den Endpunkt POST /v2/resource_instances, um eine neue Instanz zu erstellen (bereitzustellen). Übergib einen JSON-Text mit dem Header "Content-Type: application/json".

Erforderliche Felder:

• name — Ein für Menschen lesbarer Name für die Instanz.

• target — Die Region, z. B. us-east oder eu-de.

• resource_plan_id — Der Plan für diese Instanz. Siehe die Tabelle der Plan-IDs.

• resource_group — Die zu verwendende Ressourcengruppe.

Du kannst auch ein Objekt parameters einfügen, um quantenspezifische Werte festzulegen:

• instance_limit_seconds — Integer oder null. Das Nutzungszeitlimit für die Instanz. Siehe Zuteilungslimits für Instanzen festlegen.

• usage_allocation_seconds — Integer oder null. Die dieser Instanz zugewiesene Zeit, die vom Fair-Share-Scheduler genutzt wird, um die Priorität in der Warteschlange zu bestimmen. Siehe Zuteilungslimits für Instanzen festlegen. Gilt nicht für Pay-As-You-Go-Instanzen.

• backends — Array von Strings. Die Erlaubnisliste der Backend-Namen, die für diese Instanz verfügbar sind. ["ANY"] bedeutet, dass alle Backends des Plans verfügbar sind. [] bedeutet, dass keine Backends verfügbar sind.

cURL

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
      }
  }'

Python

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

Qiskit Functions-Zugriff für eine Instanz konfigurieren

Verwende diese Anleitung, um den Qiskit Functions-Zugriff auf einer bestehenden IBM Quantum Compute Service-Instanz mithilfe der IBM Cloud Resource Controller API zu konfigurieren. Führe die Schritte der Reihe nach aus, da die Befehle aufeinander aufbauen. Variablen wie das Token und die URL werden beispielsweise in einem Schritt festgelegt und in späteren Schritten wiederverwendet.

Voraussetzungen

• Ein IBM Cloud API-Schlüssel (auch Token genannt). Erstelle deinen API-Schlüssel bei Bedarf über das Dashboard.

• Die CRN der Instanz, die du konfigurieren möchtest. Die CRN der Instanz findest du auf deiner Instanzen-Seite.

Schritt 1: Bearer-Token abrufen

Tausche deinen API-Schlüssel gegen ein Bearer-Token ein. Du übergibst dieses Token im Autorisierungsheader aller Resource-Controller-Anfragen. Führe den folgenden Code aus, um ein Bearer-Token zu generieren:

cURL

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 .

Python

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) 

Die Antwort enthält ein Feld access_token, das dein Bearer-Token ist. Kopiere diesen Wert.

Schritt 2: Zugriff überprüfen

Bevor du Änderungen vornimmst, bestätige, dass dein Token funktioniert, und überprüfe die aktuelle Instanzkonfiguration.

cURL

Wichtig

Die CRN muss im Pfad manuell URL-codiert werden. Ersetze jedes : durch %3A und jedes / durch %2F. Zum Beispiel wird crn:v1:bluemix:... zu 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>'

Python

import urllib.parse

crn = "<YOUR_INSTANCE_CRN>"
# Die CRN wird in den Pfad URL-codiert.
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"])

Eine Antwort mit 200 OK bestätigt, dass dein Token gültig ist. Die aktuelle Instanzkonfiguration befindet sich im Feld extensions der Antwort. Verwende dieses Feld anstelle von parameters, das veraltet sein könnte.

Schritt 3: Die Qiskit-Functions-Konfiguration auf Kontoebene nachschlagen

Einer Instanz kann nur der Zugriff auf das gewährt werden, wozu das Konto berechtigt ist. Bevor du die Instanz konfigurierst, schlage die Kontokonfiguration nach, damit du weißt, welche Funktionen, Geschäftsmodelle und Berechtigungen zur Vergabe verfügbar sind. Dies ist die maßgebliche Quelle für die Werte, die du in Schritt 4 sendest.

Rufe GET /accounts/{id} in der Qiskit Runtime API mit deinem API-Schlüssel auf. {id} ist deine Konto-ID ohne das Präfix a/. Du findest sie in der Instanz-CRN (crn:v1:bluemix:public:quantum-computing:...:a/<ACCOUNT_ID>:...).

cURL

curl --request GET \
--url 'https://quantum.cloud.ibm.com/api/v1/accounts/<ACCOUNT_ID>' \
--header 'Authorization: apikey <YOUR_API_KEY>'

Python

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

Jeder Plan in der Antwort enthält ein functions-Array und, falls konfiguriert, ein custom_functions-Objekt. Diese listen die genauen Werte für Name, Anbieter, Geschäftsmodell und Berechtigungen auf, die du einer Instanz unter diesem Plan gewähren kannst.

hinweis

GET /accounts/{id} zeigt, was auf Kontoebene gewährt werden kann. GET /functions (siehe Ergebnis überprüfen) zeigt, was einer bestimmten Instanz bereits gewährt wurde. Verwende den account-Endpunkt, um gültige Werte zu ermitteln, und den functions-Endpunkt, um das Ergebnis zu bestätigen.

Schritt 4: Funktionszugriff konfigurieren

Aktualisiere die Instanz, um Zugriff auf Catalog Functions und Custom Functions zu gewähren.

Wichtige Hinweise

• Die Werte name, provider und business_model in functions müssen genau mit den auf Kontoebene konfigurierten Einträgen übereinstimmen (siehe den vorherigen Schritt). Berechtigungen müssen eine nicht leere Teilmenge der Berechtigungen des Kontos für diese Funktion sein. Ebenso muss custom_functions.permissions eine nicht leere Teilmenge der custom_functions-Berechtigungen des Kontos sein.
• Füge bei jedem PATCH einen Zeitstempel in parameters ein. Der Resource Controller dedupliziert PATCH-Anfragen, indem er die eingehenden parameters mit dem zuletzt gespeicherten Wert vergleicht. Stimmen sie überein, wird die Anfrage stillschweigend mit 200 OK verworfen, ohne den Dienst zu erreichen. Füge einen sich ändernden Zeitstempelwert ein, um dies zu verhindern.

cURL

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"
    ]
  }
}
}'

Python

from datetime import datetime, timezone

# Ein sich ändernder Zeitstempel verhindert, dass der Resource Controller die Anfrage dedupliziert.
_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"])

Eine Antwort mit 200 OK bedeutet, dass die Aktualisierung erfolgreich war. Die aktualisierte Konfiguration erscheint im Feld extensions der Antwort.

Funktionszugriff entfernen

Catalog Functions

Um Catalog Functions von einer Instanz zu entfernen, sende ein PATCH mit "functions": null:

cURL

--data '{
"parameters": {
"timestamp": "2026-06-30T00:00:01Z",
"functions": null
}
}'

Python

body = {"parameters": {"timestamp": timestamp, "functions": None}}
resp = requests.patch(instance_url, headers=headers, json=body, timeout=30)
resp.raise_for_status()

Das Setzen von "functions": [] (ein leeres Array) löscht Catalog Functions ebenfalls. null ist die kanonische Form.

Custom Functions

Um Custom Functions von einer Instanz zu entfernen, sende ein PATCH mit "custom_functions": null:

cURL

--data '{
"parameters": {
"timestamp": "2026-06-30T00:00:02Z",
"custom_functions": null
}
}'

Python

body = {"parameters": {"timestamp": timestamp, "custom_functions": None}}
resp = requests.patch(instance_url, headers=headers, json=body, timeout=30)
resp.raise_for_status()

Das Setzen von "custom_functions": {"permissions": []} löscht Custom Functions ebenfalls. null ist die kanonische Form.

Ergebnis überprüfen

Um zu bestätigen, dass die Instanz über die korrekte Qiskit Functions-Konfiguration verfügt, verwende GET /functions aus der Qiskit Runtime API anstelle des Resource Controllers. Der gespeicherte Status des Resource Controllers kann veraltet sein, wenn Änderungen auf Kontoebene die Instanz außerhalb des Resource Controllers aktualisiert haben.

cURL

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

Python

# Der Service-CRN-Header verwendet die rohe CRN, nicht die URL-codierte Form.
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())

Die Antwort listet die Funktionen auf, auf die die Instanz derzeit Zugriff hat.