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

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

Todos los endpoints de Resource Controller requieren que te autentiques pasando un encabezado llamado Authorization con el token bearer. Consulta la guía de configuración de la API REST.

Obtener una instancia

Usa el endpoint GET /v2/resource_instances/{crn} para obtener información sobre una instancia particular. 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 cuántica tanto en parameters como en extensions. extensions almacena los metadatos normalizados de la instancia, mientras que parameters solo almacena la solicitud más reciente para modificar la instancia. Por lo tanto, debes leer desde extensions en lugar de parameters.

El objeto extensions incluye estos campos:

• instance_limit_seconds — Entero, o null. El límite de tiempo de uso para la instancia. Consulta Establecer límites de asignación de instancias.

• usage_allocation_seconds — Entero, o null. El tiempo asignado a esta instancia, utilizado por el programador de recursos compartidos para determinar la prioridad en la cola. Consulta Establecer límites de asignación de instancias.

• backends — Matriz de cadenas. La lista de permitidos de nombres de backends disponibles para esta instancia. ["ANY"] significa que todos los backends del plan están disponibles (el valor predeterminado). [] significa que no hay backends disponibles.

El campo backends puede estar desactualizado

El campo backends en el objeto extensions puede estar desactualizado. Esto puede ocurrir cuando IBM Quantum Support cambia tu cuenta de una manera que afecta a las instancias. Por ejemplo, cuando se elimina un backend de una cuenta, se actualizará el campo backends de la instancia, pero ese cambio actualmente aún no se refleja en la API de Resource Controller.

En su lugar, la solución alternativa actual es usar la API REST de IBM Quantum Compute Service con el endpoint GET /v1/backends. (Asegúrate de establecer el encabezado Service-CRN con el CRN de tu instancia.)

cURL

El CRN debe estar codificado en URL en la ruta. Reemplaza cada : por %3A y cada / por %2F. Por ejemplo, crn:v1:bluemix:... se convierte en 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>"
# Usamos urllib.parse.quote para codificar el 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())

Obtener una lista de todas las instancias

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

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

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

Cada resultado incluye el mismo campo extensions descrito en Obtener una instancia.

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

Actualizar una instancia

Usa el endpoint PATCH /v2/resource_instances/{crn} 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.

Pasa un objeto JSON parameters en el cuerpo de la solicitud con los campos que quieres cambiar, junto con el encabezado "Content-Type: application/json". Los campos omitidos permanecen sin cambios.

• instance_limit_seconds — Entero, o null. El límite de tiempo de uso para la instancia. Consulta Establecer límites de asignación de instancias.

• usage_allocation_seconds — Entero, o null. El tiempo asignado a esta instancia, utilizado por el programador de recursos compartidos para determinar la prioridad en la cola. Consulta Establecer límites de asignación de instancias. No aplica a las instancias Pay-As-You-Go.

• backends — Matriz de cadenas. La lista de permitidos de nombres de backends disponibles para esta instancia. ["ANY"] significa que todos los backends del plan están disponibles. [] significa que no hay backends disponibles.

Incluye siempre una marca de tiempo única

La API ignora silenciosamente la solicitud si parameters es idéntico a la solicitud anterior. En el objeto parameters, incluye siempre un campo timestamp establecido en la hora actual para que cada solicitud se trate como única.

La respuesta del endpoint es similar a la de obtener una instancia, incluida la forma en que maneja el objeto extensions.

cURL

El CRN debe estar codificado en URL en la ruta. Reemplaza cada : por %3A y cada / por %2F. Por ejemplo, crn:v1:bluemix:... se convierte en 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>"
# Usamos urllib.parse.quote para codificar el 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())

Crear una nueva instancia

Usa el endpoint POST /v2/resource_instances para crear (aprovisionar) una nueva instancia. Pasa un cuerpo JSON con el encabezado "Content-Type: application/json".

Campos requeridos:

• name — Un nombre legible para la instancia.

• target — La región, como us-east o eu-de.

• resource_plan_id — El plan para esta instancia. Consulta la tabla de ID de planes.

• resource_group — El grupo de recursos a usar.

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

• instance_limit_seconds — Entero, o null. El límite de tiempo de uso para la instancia. Consulta Establecer límites de asignación de instancias.

• usage_allocation_seconds — Entero, o null. El tiempo asignado a esta instancia, utilizado por el programador de recursos compartidos para determinar la prioridad en la cola. Consulta Establecer límites de asignación de instancias. No aplica a las instancias Pay-As-You-Go.

• backends — Matriz de cadenas. La lista de permitidos de nombres de backends disponibles para esta instancia. ["ANY"] significa que todos los backends del plan están disponibles. [] significa que no hay backends disponibles.

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

Configurar el acceso a Qiskit Functions en una instancia

Usa estas instrucciones para configurar el acceso a Qiskit Functions en una instancia existente de IBM Quantum Compute Service utilizando la API de IBM Cloud Resource Controller. Sigue las instrucciones en orden, ya que los comandos se basan unos en otros. Por ejemplo, variables como el token y la URL se establecen en un paso y se reutilizan en pasos posteriores.

Requisitos previos

• Una clave de API de IBM Cloud (también llamada token). Si es necesario, crea tu clave de API en el panel de control.

• El CRN de la instancia que deseas configurar. El CRN de la instancia aparece en tu página de Instancias.

Paso 1: Obtener un token bearer

Intercambia tu clave de API por un token bearer. Pasarás este token en el encabezado de autorización de todas las solicitudes al resource controller. Ejecuta el siguiente código para generar un token bearer:

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) 

La respuesta incluye un campo access_token, que es tu token bearer. Copia este valor.

Paso 2: Verificar el acceso

Antes de hacer cualquier cambio, confirma que tu token funciona e inspecciona la configuración actual de la instancia.

cURL

Importante

El CRN debe estar codificado manualmente en URL en la ruta. Reemplaza cada : por %3A y cada / por %2F. Por ejemplo, crn:v1:bluemix:... se convierte en 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>"
# El CRN se codificará en URL en la ruta.
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 está en el campo extensions de la respuesta. Usa este campo en lugar de parameters, que podría estar desactualizado.

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

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

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

Cada plan en la respuesta incluye una matriz functions y, si está configurado, un objeto custom_functions. Estos enumeran el nombre exacto, el proveedor, el modelo de negocio y los valores de permisos que puedes conceder a una instancia bajo ese plan.

nota

GET /accounts/{id} muestra lo que se puede conceder a nivel de cuenta. GET /functions (consulta Verificar el resultado) muestra lo que ya se ha concedido a una instancia específica. Usa el endpoint de cuenta para descubrir los valores válidos y el endpoint de funciones para confirmar el resultado.

Paso 4: Configurar el acceso a funciones

Actualiza la instancia para conceder acceso a Catalog Functions y Custom Functions.

Notas importantes

• Los valores name, provider y business_model en functions deben coincidir exactamente con las entradas configuradas a nivel de cuenta (consulta el paso anterior). Los permisos deben ser un subconjunto no vacío de los permisos de la cuenta para esa función. De manera similar, custom_functions.permissions debe ser un subconjunto no vacío de los permisos custom_functions de la cuenta.
• Incluye una marca de tiempo en parameters en cada PATCH. El Resource Controller deduplica las solicitudes PATCH comparando los parameters entrantes con el último valor almacenado. Si coinciden, la solicitud se descarta silenciosamente con 200 OK sin llegar al servicio. Incluye un valor de marca de tiempo cambiante para evitar esto.

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

# Una marca de tiempo cambiante evita que el Resource Controller deduplique la solicitud.
_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 éxito. La configuración actualizada aparece en el campo extensions de la respuesta.

Eliminar el acceso a funciones

Catalog Functions

Para eliminar Catalog Functions de una instancia, envía un PATCH con "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()

Establecer "functions": [] (una matriz vacía) elimina Catalog Functions de forma equivalente. null es la forma canónica.

Custom Functions

Para eliminar Custom Functions de una instancia, envía un PATCH con "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()

Establecer "custom_functions": {"permissions": []} elimina las funciones personalizadas de forma equivalente. null es la forma canónica.

Verificar el resultado

Para confirmar que la instancia tiene la configuración correcta de Qiskit Functions, usa GET /functions de la API de Qiskit Runtime en lugar del Resource Controller. El estado almacenado del Resource Controller podría estar desactualizado si cambios a nivel de cuenta actualizaron la instancia fuera del Resource Controller.

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

# El encabezado Service-CRN toma el CRN en bruto, no la forma codificada 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 respuesta enumera las funciones a las que la instancia tiene acceso actualmente.