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

Vous pouvez utiliser l'API REST de l' IBM Cloud® Resource Controller pour récupérer, créer et mettre à jour des instances par programmation.

Tous les points de terminaison de l' Resource Controller exigent que vous vous authentifiiez en transmettant un en-tête appelé Authorization contenant le jeton « bearer ». Consultez le guide de configuration de l'API REST.

Obtenir une instance

Utilisez le GET /v2/resource_instances/{crn} point de terminaison pour obtenir des informations sur une instance spécifique. L' CRN e doit être encodée selon le format « URL » dans le chemin d'accès.

Outre les champs standard de l' Resource Controller, la réponse comprend des champs spécifiques à Quantum, tant parameters dans que dans extensions. extensions stocke les métadonnées normalisées de l'instance, tandis que parameters ne stocke que la dernière demande de modification de l'instance. Par conséquent, vous devriez lire à partir de extensions plutôt que de parameters.

extensions L'objet comprend les champs suivants :

• instance_limit_seconds — Nombre entier, ou null. La durée maximale d'utilisation de l'instance. Voir « Définir les limites d'allocation des instances ».
• usage_allocation_seconds — Nombre entier, ou null. Le temps alloué à cette instance, utilisé par le planificateur « fair-share » pour déterminer la priorité dans la file d'attente. Voir « Définir les limites d'allocation des instances ».
• backends — Tableau de chaînes de caractères. La liste blanche des noms de backends disponibles pour cette instance. ["ANY"] signifie que tous les backends du forfait sont disponibles (c'est le réglage par défaut). [] signifie qu'aucun backend n'est disponible.

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

Obtenir la liste de toutes les instances

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

Si votre compte comporte plusieurs forfaits et que vous souhaitez filtrer par forfait, définissez le resource_plan_id paramètre de requête sur l'une des valeurs suivantes :

Chaque résultat comprend les mêmes extensions champs que ceux décrits dans la section « Obtenir une instance ».

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

Utilisez le PATCH /v2/resource_instances/{crn} point de terminaison pour mettre à jour la limite, l'allocation et les backends autorisés pour une instance. L' CRN e doit être encodée selon le format « URL » dans le chemin d'accès.

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

• instance_limit_seconds — Nombre entier, ou null. La durée maximale d'utilisation de l'instance. Voir « Définir les limites d'allocation des instances ».
• usage_allocation_seconds — Nombre entier, ou null. Le temps alloué à cette instance, utilisé par le planificateur « fair-share » pour déterminer la priorité dans la file d'attente. Voir « Définir les limites d'allocation des instances ». Ne s'applique pas aux instances en mode « Pay-As-You-Go ».
• backends — Tableau de chaînes de caractères. La liste blanche des noms de backends disponibles pour cette instance. ["ANY"] signifie que tous les backends du forfait sont disponibles. [] signifie qu'aucun backend n'est disponible.

La réponse du point de terminaison est similaire à celle obtenue lors de la création d'une instance, notamment en ce qui concerne la manière dont il gère l'objet extensions .

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

Créer une instance

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

Champs requis :

• name — Un nom lisible par l'utilisateur pour l'instance.
• target — La région, comme us-east ou eu-de.
• resource_plan_id — Le plan pour cette instance. Consultez le tableau des identifiants de plan.
• resource_group — Le groupe de ressources à utiliser.

Vous pouvez également inclure un parameters objet pour définir des valeurs spécifiques à Quantum :

• instance_limit_seconds — Nombre entier, ou null. La durée maximale d'utilisation de l'instance. Voir « Définir les limites d'allocation des instances ».
• usage_allocation_seconds — Nombre entier, ou null. Le temps alloué à cette instance, utilisé par le planificateur « fair-share » pour déterminer la priorité dans la file d'attente. Voir « Définir les limites d'allocation des instances ». Ne s'applique pas aux instances en mode « Pay-As-You-Go ».
• backends — Tableau de chaînes de caractères. La liste blanche des noms de backends disponibles pour cette instance. ["ANY"] signifie que tous les backends du forfait sont disponibles. [] signifie qu'aucun backend n'est disponible.

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 à Qiskit Functions sur une instance

Suivez ces instructions pour configurer l'accès à « Qiskit Functions » sur une instance existante d' IBM Quantum Compute Service à l'aide de l'API IBM Cloud Resource Controller. Suivez les instructions dans l'ordre, car les commandes s'enchaînent les unes après les autres. Par exemple, des variables telles que le jeton et l' URL e sont définies en une seule étape et réutilisées dans les étapes suivantes.

Prérequis

• Une clé API d' IBM Cloud s (également appelée « jeton »). Si nécessaire, créez votre clé API sur le tableau de bord.
• L' CRN e de l'instance que vous souhaitez configurer. L' CRN s relatives à l'instance figurent sur votre page « Instances ».

Étape 1 : Obtenir un jeton au porteur

Échangez votre clé API contre un jeton « bearer ». Vous devrez transmettre ce jeton dans l'en-tête d'autorisation de toutes les requêtes adressées au contrôleur de ressources. Exécutez le code suivant pour générer un jeton « bearer » :

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 comprend un access_token champ, qui correspond à votre jeton « bearer ». Copiez cette valeur.

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

Avant d'effectuer la moindre modification, assurez-vous que votre jeton fonctionne et vérifiez la configuration actuelle de l'instance.

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>"
# The CRN will be URL-encoded into the path.
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 votre jeton est valide. La configuration actuelle de l'instance se trouve dans le champ « extensions » de la réponse. Utilisez ceci à la place des paramètres, qui pourraient être obsolètes.

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

Une instance ne peut se voir accorder l'accès qu'aux éléments auxquels le compte a droit. Avant de configurer l'instance, consultez la configuration du compte afin de savoir quelles fonctions, quels modèles commerciaux et quelles autorisations vous pouvez attribuer. Il s'agit de la source de référence pour les valeurs que vous devrez saisir à l'étape 4.

Appelez l'API « Qiskit Runtime » à GET /accounts/{id} l'aide de votre clé API. Il {id} s'agit de l'identifiant de votre compte sans le préfixe a/ . Vous pouvez le trouver à partir de l'instance CRN (crn:v1:bluemix:public:quantum-computing:...:a/<ACCOUNT_ID>:...).

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 comprend un tableau de fonctions et, s'il est configuré, un objet custom_functions . Ces informations précisent le nom exact, le fournisseur, le modèle économique et les autorisations que vous pouvez attribuer à une instance dans le cadre de cette offre.

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

Mettez à jour l'instance afin d'accorder l'accès aux fonctions du catalogue et aux fonctions personnalisées.

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

# A changing timestamp keeps the Resource Controller from de-duplicating the request.
_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 que l'opération a réussi. La configuration mise à jour apparaît dans le champ « extensions » de la réponse.

Supprimer l'accès aux fonctions

Fonctions du catalogue

Pour supprimer des fonctions de catalogue d'une instance, envoyez une requête PATCH contenant les éléments suivants "functions": null:

--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) revient à effacer les fonctions du catalogue. null C'est la forme canonique.

Fonctions personnalisées

Pour supprimer des fonctions personnalisées d'une instance, envoyez une requête PATCH contenant "custom_functions": null:

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

La définition de cette option efface également "custom_functions": {"permissions": []} les fonctions personnalisées. null C'est la forme canonique.

Vérifier le résultat

Pour vérifier que l'instance dispose de la configuration correcte d' Qiskit Functions, utilisez GET /functions l'API Qiskit Runtime à la place de Resource Controller. L'état enregistré de l' Resource Controller peut être obsolète si des modifications au niveau du compte ont mis à jour l'instance en dehors de l' Resource Controller.

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

# The Service-CRN header takes the raw CRN, not the URL-encoded 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())

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