Utiliser l'API IBM Cloud Resource Controller pour la gestion des instances

Tu peux utiliser l'API REST IBM Cloud® Resource Controller pour obtenir, créer et mettre à jour des instances de manière programmatique.

Tous les points de terminaison du Resource Controller exigent que tu t'authentifies en transmettant un en-tête appelé Authorization avec le jeton porteur. Consulte le guide de configuration de l'API REST.

Obtenir une instance

Utilise le point de terminaison GET /v2/resource_instances/{crn} pour obtenir des informations sur une instance particulière. Le CRN doit être encodé en URL dans le chemin.

En plus des champs standard du Resource Controller, la réponse inclut des champs spécifiques à quantum à la fois dans parameters et dans extensions. extensions stocke les métadonnées normalisées de l'instance, tandis que parameters ne stocke que la demande de modification la plus récente de l'instance. Par conséquent, tu devrais lire à partir de extensions plutôt que de parameters.

L'objet extensions inclut ces champs :

instance_limit_seconds — Entier, ou null. La limite de temps d'utilisation pour l'instance. Voir Définir les limites d'allocation d'instance.
usage_allocation_seconds — Entier, ou null. Le temps alloué à cette instance, utilisé par l'ordonnanceur à partage équitable pour déterminer la priorité dans la file d'attente. Voir Définir les limites d'allocation d'instance.
backends — Tableau de chaînes. La liste d'autorisation des noms de backends disponibles pour cette instance. ["ANY"] signifie que tous les backends du plan sont disponibles (valeur par défaut). [] signifie qu'aucun backend n'est disponible.

Le champ backends peut être obsolète

Le champ backends de l'objet extensions peut être obsolète. Cela peut se produire lorsque le support IBM Quantum modifie ton compte d'une manière qui affecte les instances. Par exemple, lorsqu'un backend est retiré d'un compte, cela met à jour les backends de l'instance, mais ce changement n'est actuellement pas encore reflété dans l'API Resource Controller.

À la place, la solution de contournement actuelle consiste à utiliser l'API REST IBM Quantum Compute Service avec le point de terminaison GET /v1/backends. (Assure-toi de définir l'en-tête Service-CRN sur le CRN de ton instance.)

cURL
Python

Le CRN doit être encodé en URL dans le chemin. Remplace chaque : par %3A et chaque / par %2F. Par exemple, crn:v1:bluemix:... devient 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>"
# Nous utilisons urllib.parse.quote pour encoder le CRN en URL.
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())

Obtenir une liste de toutes les instances

Utilise le point de terminaison GET /v2/resource_instances pour obtenir une liste de toutes tes instances. Définis le paramètre de requête resource_id sur b6049020-80f4-11eb-a0f7-e35ec9b4054f pour filtrer les instances IBM Quantum®.

Si ton compte comporte plusieurs plans et que tu souhaites filtrer par plan, définis le paramètre de requête resource_plan_id sur l'une des valeurs suivantes :

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`

Chaque résultat inclut le même champ extensions que celui décrit dans Obtenir une 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())

Mettre à jour une instance

Utilise le point de terminaison PATCH /v2/resource_instances/{crn} pour mettre à jour la limite, l'allocation et les backends autorisés pour une instance. Le CRN doit être encodé en URL dans le chemin.

Transmets un objet JSON parameters dans le corps de la requête avec les champs que tu souhaites modifier, ainsi que l'en-tête "Content-Type: application/json". Les champs omis restent inchangés.

instance_limit_seconds — Entier, ou null. La limite de temps d'utilisation pour l'instance. Voir Définir les limites d'allocation d'instance.
usage_allocation_seconds — Entier, ou null. Le temps alloué à cette instance, utilisé par l'ordonnanceur à partage équitable pour déterminer la priorité dans la file d'attente. Voir Définir les limites d'allocation d'instance. Ne s'applique pas aux instances Pay-As-You-Go.
backends — Tableau de chaînes. La liste d'autorisation des noms de backends disponibles pour cette instance. ["ANY"] signifie que tous les backends du plan sont disponibles. [] signifie qu'aucun backend n'est disponible.

Inclus toujours un horodatage unique

L'API ignore silencieusement la requête si parameters est identique à la requête précédente. Dans l'objet parameters, inclus toujours un champ timestamp défini sur l'heure actuelle afin que chaque requête soit traitée comme unique.

La réponse du point de terminaison est similaire à celle de l'obtention d'une instance, y compris la façon dont elle gère l'objet extensions.

cURL
Python

Le CRN doit être encodé en URL dans le chemin. Remplace chaque : par %3A et chaque / par %2F. Par exemple, crn:v1:bluemix:... devient 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>"
# Nous utilisons urllib.parse.quote pour encoder le CRN en URL.
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())

Créer une nouvelle instance

Utilise le point de terminaison POST /v2/resource_instances pour créer (provisionner) une nouvelle instance. Transmets un corps JSON avec l'en-tête "Content-Type: application/json".

Champs obligatoires :

name — Un nom lisible par un humain pour l'instance.
target — La région, par exemple us-east ou eu-de.
resource_plan_id — Le plan pour cette instance. Voir le tableau des ID de plan.
resource_group — Le groupe de ressources à utiliser.

Tu peux également inclure un objet parameters pour définir des valeurs spécifiques à quantum :

instance_limit_seconds — Entier, ou null. La limite de temps d'utilisation pour l'instance. Voir Définir les limites d'allocation d'instance.
usage_allocation_seconds — Entier, ou null. Le temps alloué à cette instance, utilisé par l'ordonnanceur à partage équitable pour déterminer la priorité dans la file d'attente. Voir Définir les limites d'allocation d'instance. Ne s'applique pas aux instances Pay-As-You-Go.
backends — Tableau de chaînes. La liste d'autorisation des noms de backends disponibles pour cette instance. ["ANY"] signifie que tous les backends du plan sont disponibles. [] signifie qu'aucun backend n'est disponible.

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

Configurer l'accès aux Qiskit Functions sur une instance

Utilise ces instructions pour configurer l'accès aux Qiskit Functions sur une instance IBM Quantum Compute Service existante à l'aide de l'API IBM Cloud Resource Controller. Suis les instructions dans l'ordre, car les commandes s'appuient les unes sur les autres. Par exemple, des variables telles que le jeton et l'URL sont définies à une étape et réutilisées dans les étapes suivantes.

Prérequis

Une clé API IBM Cloud (aussi appelée jeton). Si nécessaire, crée ta clé API sur le tableau de bord.
Le CRN de l'instance que tu souhaites configurer. Le CRN de l'instance est répertorié sur ta page Instances.

Étape 1 : Obtenir un jeton porteur

Échange ta clé API contre un jeton porteur. Tu transmettras ce jeton dans l'en-tête d'autorisation de toutes les requêtes du Resource Controller. Exécute le code suivant pour générer un jeton porteur :

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) 

La réponse inclut un champ access_token, qui est ton jeton porteur. Copie cette valeur.

Étape 2 : Vérifier l'accès

Avant d'apporter des modifications, confirme que ton jeton fonctionne et vérifie la configuration actuelle de l'instance.

cURL
Python

Important

Le CRN doit être encodé manuellement en URL dans le chemin. Remplace chaque : par %3A et chaque / par %2F. Par exemple, crn:v1:bluemix:... devient 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>"
# Le CRN sera encodé en URL dans le chemin.
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"])

Une réponse 200 OK confirme que ton jeton est valide. La configuration actuelle de l'instance se trouve dans le champ extensions de la réponse. Utilise celui-ci plutôt que parameters, qui pourrait être obsolète.

Étape 3 : Rechercher la configuration des fonctions au niveau du compte

Une instance ne peut se voir accorder l'accès qu'à ce à quoi le compte a droit. Avant de configurer l'instance, recherche la configuration du compte afin de connaître les fonctions, modèles économiques et autorisations disponibles à accorder. C'est la source de vérité pour les valeurs que tu enverras à l'étape 4.

Appelle GET /accounts/{id} sur l'API Qiskit Runtime avec ta clé API. {id} est ton ID de compte sans le préfixe a/. Tu peux le trouver à partir du CRN de l'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"))

Chaque plan de la réponse inclut un tableau functions et, si configuré, un objet custom_functions. Ceux-ci répertorient le nom exact, le fournisseur, le modèle économique et les valeurs d'autorisations que tu peux accorder à une instance dans le cadre de ce plan.

remarque

GET /accounts/{id} montre ce qui peut être accordé au niveau du compte. GET /functions (voir Vérifier le résultat) montre ce qui a déjà été accordé à une instance spécifique. Utilise le point de terminaison account pour découvrir les valeurs valides, et le point de terminaison functions pour confirmer le résultat.

Étape 4 : Configurer l'accès aux fonctions

Mets à jour l'instance pour accorder l'accès aux Catalog Functions et Custom Functions.

Remarques importantes

Les valeurs name, provider et business_model dans functions doivent correspondre exactement aux entrées configurées au niveau du compte (voir l'étape précédente). Les autorisations doivent être un sous-ensemble non vide des autorisations du compte pour cette fonction. De même, custom_functions.permissions doit être un sous-ensemble non vide des autorisations custom_functions du compte.
Inclus un horodatage dans parameters à chaque PATCH. Le Resource Controller déduplique les requêtes PATCH en comparant les parameters entrants à la dernière valeur qu'il a stockée. S'ils correspondent, la requête est abandonnée silencieusement avec 200 OK sans atteindre le service. Inclus une valeur d'horodatage changeante pour éviter cela.

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 horodatage changeant empêche le Resource Controller de dédupliquer la requête.
_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"])

Une réponse 200 OK indique le succès. La configuration mise à jour apparaît dans le champ extensions de la réponse.

Supprimer l'accès aux fonctions

Catalog Functions

Pour supprimer les Catalog Functions d'une instance, envoie un PATCH avec "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()

Définir "functions": [] (un tableau vide) efface également les Catalog Functions de manière équivalente. null est la forme canonique.

Custom Functions

Pour supprimer les Custom Functions d'une instance, envoie un PATCH avec "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()

Définir "custom_functions": {"permissions": []} efface également les fonctions personnalisées de manière équivalente. null est la forme canonique.

Vérifier le résultat

Pour confirmer que l'instance dispose de la configuration Qiskit Functions correcte, utilise GET /functions de l'API Qiskit Runtime plutôt que le Resource Controller. L'état stocké du Resource Controller peut être obsolète si des modifications au niveau du compte ont mis à jour l'instance en dehors du 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>'

# L'en-tête Service-CRN utilise le CRN brut, et non la forme encodée en 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())

La réponse répertorie les fonctions auxquelles l'instance a actuellement accès.

Obtenir une instance​

Obtenir une liste de toutes les instances​

Mettre à jour une instance​

Créer une nouvelle instance​

Configurer l'accès aux Qiskit Functions sur une instance​

Prérequis​

Étape 1 : Obtenir un jeton porteur​

Étape 2 : Vérifier l'accès​

Étape 3 : Rechercher la configuration des fonctions au niveau du compte​

Étape 4 : Configurer l'accès aux fonctions​

Supprimer l'accès aux fonctions​

Catalog Functions​

Custom Functions​

Vérifier le résultat​