Utiliza la API de IBM Cloud Resource Controller para la gestión de instancias

Puedes utilizar la API REST de IBM Cloud® Resource Controller para obtener, crear y actualizar instancias mediante programación.

Todos los puntos finales de Resource Controller requieren que te autentifiques enviando un encabezado llamado Authorization con el token «bearer». Consulta la guía de configuración de la API REST.

Obtener una instancia

Utiliza el GET /v2/resource_instances/{crn} punto final para obtener información sobre una instancia concreta. El « CRN » debe estar codificado en « URL » en la ruta.

Además de los campos estándar de « Resource Controller », la respuesta incluye campos específicos de la física cuántica tanto parameters en como en extensions. extensions almacena los metadatos normalizados de la instancia, mientras que parameters solo almacena la última solicitud de modificación de la instancia. parametersPor lo tanto, deberías leer «de» extensions en lugar de «».

El extensions objeto incluye los siguientes campos:

• instance_limit_seconds — Número entero, o null. El límite de tiempo de uso de la instancia. Consulta «Establecer límites de asignación de instancias ».
• usage_allocation_seconds — Número entero, o null. El tiempo asignado a esta instancia, que utiliza el programador de reparto equitativo para determinar la prioridad de la cola. Consulta «Establecer límites de asignación de instancias ».
• backends — Matriz de cadenas. La lista de nombres de backends permitidos para esta instancia. ["ANY"] significa que todos los backends del plan están disponibles (es la opción predeterminada). [] significa que no hay backends disponibles.

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

Obtener una lista de todas las instancias

Utiliza el GET /v2/resource_instances punto final para obtener una lista de todas tus instancias. Establece el resource_id parámetro de consulta en b6049020-80f4-11eb-a0f7-e35ec9b4054f para filtrar las instancias de IBM Quantum®.

Si tu cuenta tiene varios planes y quieres filtrar por plan, establece el resource_plan_id parámetro de consulta en uno de los siguientes valores:

Cada resultado incluye los mismos extensions campos que se describen en «Obtener una instancia ».

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

Actualizar una instancia

Utiliza el PATCH /v2/resource_instances/{crn} punto final para actualizar el límite, la asignación y los backends permitidos de una instancia. El « CRN » debe estar codificado en « URL » en la ruta.

"Content-Type: application/json"Incluye un parameters objeto JSON en el cuerpo de la solicitud con los campos que quieras modificar, junto con el encabezado. Los campos omitidos no se modifican.

• instance_limit_seconds — Número entero, o null. El límite de tiempo de uso de la instancia. Consulta «Establecer límites de asignación de instancias ».
• usage_allocation_seconds — Número entero, o null. El tiempo asignado a esta instancia, que utiliza el programador de reparto equitativo para determinar la prioridad de la cola. Consulta «Establecer límites de asignación de instancias ». No aplicable a las instancias de pago por uso.
• backends — Matriz de cadenas. La lista de nombres de backends permitidos para esta instancia. ["ANY"] significa que todos los backends del plan están disponibles. [] significa que no hay backends disponibles.

La respuesta del punto final es similar a la que se obtiene al recuperar una instancia, incluyendo la forma en que gestiona el extensions objeto.

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

Crear una nueva instancia

Utiliza el POST /v2/resource_instances punto final para crear (aprovisionar) una nueva instancia. Envía un cuerpo JSON con el encabezado "Content-Type: application/json".

Campos obligatorios:

• name — Un nombre legible para la instancia.
• target — La región, como us-east o eu-de.
• resource_plan_id — El plan para este caso. Consulta la tabla de identificadores de planes.
• resource_group — El grupo de recursos que se va a utilizar.

También puedes incluir un parameters objeto para establecer valores específicos de Quantum:

• instance_limit_seconds — Número entero, o null. El límite de tiempo de uso de la instancia. Consulta «Establecer límites de asignación de instancias ».
• usage_allocation_seconds — Número entero, o null. El tiempo asignado a esta instancia, que utiliza el programador de reparto equitativo para determinar la prioridad de la cola. Consulta «Establecer límites de asignación de instancias ». No aplicable a las instancias de pago por uso.
• backends — Matriz de cadenas. La lista de nombres de backends permitidos para esta instancia. ["ANY"] significa que todos los backends del plan están disponibles. [] significa que no hay backends disponibles.

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

Configurar el acceso a « Qiskit Functions » en una instancia

Sigue estas instrucciones para configurar el acceso a « Qiskit Functions » en una instancia existente de « IBM Quantum Compute Service» mediante la API de « IBM Cloud » Resource Controller. Sigue las instrucciones en el orden indicado, ya que los comandos se complementan entre sí. Por ejemplo, variables como «token» y « URL » se definen en un paso y se reutilizan en pasos posteriores.

Requisitos previos

• Una clave API de IBM Cloud (también denominada «token»). Si es necesario, crea tu clave API en el panel de control.
• El archivo « CRN » de la instancia que deseas configurar. El CRN de la instancia aparece en la página «Instancias ».

Paso 1: Obtener un token al portador

Cambia tu clave API por un token de portador. Deberás incluir este token en el encabezado de autorización de todas las solicitudes al controlador de recursos. Ejecuta el siguiente código para generar un token de acceso:

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 respuesta incluye un access_token campo, que es tu token de portador. Copia este valor.

Paso 2: Comprobar el acceso

Antes de realizar cualquier cambio, comprueba que tu token funciona y revisa la configuración actual de la instancia.

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

Una respuesta 200 OK confirma que tu token es válido. La configuración actual de la instancia se encuentra en el campo «extensions» de la respuesta. Utiliza esto en lugar de los parámetros, que podrían estar desactualizados.

Paso 3: Consultar la configuración de las funciones a nivel de cuenta

A una instancia solo se le puede conceder acceso a aquello a lo que tiene derecho la cuenta. Antes de configurar la instancia, consulta la configuración de la cuenta para saber qué funciones, modelos de negocio y permisos puedes conceder. Esta es la fuente de referencia de los valores que enviarás en el paso 4.

Realiza una llamada a GET /accounts/{id} la API de Qiskit Runtime con tu clave API. El es {id} tu ID de cuenta sin el prefijo a/ . Puedes encontrarlo en la instancia 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"))

Cada plan de la respuesta incluye una matriz de funciones y, si se ha configurado, un objeto custom_functions . En ellas se indican el nombre exacto, el proveedor, el modelo de negocio y los valores de los permisos que puedes conceder a una instancia incluida en ese plan.

Paso 4: Configurar el acceso a las funciones

Actualiza la instancia para conceder acceso a las funciones del catálogo y a las funciones personalizadas.

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

Una respuesta 200 OK indica que la operación se ha realizado con éxito. La configuración actualizada aparece en el campo «extensiones» de la respuesta.

Eliminar el acceso a las funciones

Funciones del catálogo

Para eliminar funciones del catálogo de una instancia, envía una solicitud PATCH con lo siguiente "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()

Al establecer ( "functions": [] un array vacío) se borran, de forma equivalente, las funciones del catálogo. null es la forma canónica.

Funciones personalizadas

Para eliminar funciones personalizadas de una instancia, envía una solicitud PATCH con "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()

Al establecer este valor, se borran también "custom_functions": {"permissions": []} las funciones personalizadas. null es la forma canónica.

Comprueba el resultado

Para confirmar que la instancia tiene la configuración correcta de « Qiskit Functions », utiliza la API « Qiskit RuntimeGET /functions » en lugar de la API « Resource Controller ». Es posible que el estado almacenado de « Resource Controller » esté desactualizado si se han producido cambios a nivel de cuenta que hayan actualizado la instancia fuera de « 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 respuesta enumera las funciones a las que la instancia tiene acceso actualmente.