Використання API IBM Cloud Resource Controller для керування інстансами

Ти можеш використовувати REST API IBM Cloud® Resource Controller, щоб програмно отримувати, створювати та оновлювати інстанси.

Усі кінцеві точки Resource Controller вимагають, щоб ти автентифікувався, передаючи заголовок під назвою Authorization із bearer-токеном. Дивись посібник із налаштування REST API.

Отримання інстансу

Використовуй кінцеву точку GET /v2/resource_instances/{crn}, щоб отримати інформацію про конкретний інстанс. CRN має бути закодований у форматі URL у шляху.

Окрім стандартних полів Resource Controller, відповідь включає специфічні для квантових обчислень поля як у parameters, так і в extensions. extensions зберігає нормалізовані метадані інстансу, тоді як parameters зберігає лише останній запит на зміну інстансу. Тому тобі слід читати з extensions, а не з parameters.

Об'єкт extensions включає такі поля:

• instance_limit_seconds — Ціле число, або null. Ліміт часу використання для інстансу. Дивись Встановлення лімітів розподілу інстансу.

• usage_allocation_seconds — Ціле число, або null. Час, виділений цьому інстансу, який використовується планувальником справедливого розподілу для визначення пріоритету в черзі. Дивись Встановлення лімітів розподілу інстансу.

• backends — Масив рядків. Список дозволених імен бекендів, доступних для цього інстансу. ["ANY"] означає, що всі бекенди на плані доступні (за замовчуванням). [] означає, що жоден бекенд не доступний.

Поле backends може бути застарілим

Поле backends в об'єкті extensions може бути застарілим. Це може статися, коли підтримка IBM Quantum змінює твій обліковий запис у спосіб, що впливає на інстанси. Наприклад, коли бекенд видаляється з облікового запису, це оновить backends для інстансу, але ця зміна наразі ще не відображена в API Resource Controller.

Натомість поточним обхідним рішенням є використання REST API IBM Quantum Compute Service з кінцевою точкою GET /v1/backends. (Переконайся, що ти встановив заголовок Service-CRN на CRN твого інстансу.)

cURL

CRN має бути закодований у форматі URL у шляху. Заміни кожен : на %3A, а кожен / на %2F. Наприклад, crn:v1:bluemix:... стає 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())

Отримання списку всіх інстансів

Використовуй кінцеву точку GET /v2/resource_instances, щоб отримати список усіх твоїх інстансів. Встанови параметр запиту resource_id на b6049020-80f4-11eb-a0f7-e35ec9b4054f, щоб відфільтрувати інстанси IBM Quantum®.

Якщо твій обліковий запис має декілька планів і ти хочеш фільтрувати за планом, встанови параметр запиту resource_plan_id на одне з наступних значень:

План	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

Кожен результат включає те саме поле extensions, що описано в Отриманні інстансу.

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

Оновлення інстансу

Використовуй кінцеву точку PATCH /v2/resource_instances/{crn}, щоб оновити ліміт, розподіл та дозволені бекенди для інстансу. CRN має бути закодований у форматі URL у шляху.

Передай JSON-об'єкт parameters у тілі запиту з полями, які ти хочеш змінити, разом із заголовком "Content-Type: application/json". Пропущені поля залишаються без змін.

• instance_limit_seconds — Ціле число, або null. Ліміт часу використання для інстансу. Дивись Встановлення лімітів розподілу інстансу.

• usage_allocation_seconds — Ціле число, або null. Час, виділений цьому інстансу, який використовується планувальником справедливого розподілу для визначення пріоритету в черзі. Дивись Встановлення лімітів розподілу інстансу. Не застосовується до інстансів Pay-As-You-Go.

• backends — Масив рядків. Список дозволених імен бекендів, доступних для цього інстансу. ["ANY"] означає, що всі бекенди на плані доступні. [] означає, що жодні бекенди не доступні.

Завжди включай унікальну мітку часу

API мовчки ігнорує запит, якщо parameters ідентичний попередньому запиту. В об'єкті parameters завжди включай поле timestamp, встановлене на поточний час, щоб кожен запит вважався унікальним.

Відповідь кінцевої точки схожа на отримання інстансу, включно з тим, як вона обробляє об'єкт extensions.

cURL

CRN має бути закодований у форматі URL у шляху. Заміни кожен : на %3A, а кожен / на %2F. Наприклад, crn:v1:bluemix:... стає 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())

Створення нового інстансу

Використовуй кінцеву точку POST /v2/resource_instances, щоб створити (виділити) новий інстанс. Передай тіло JSON із заголовком "Content-Type: application/json".

Обов'язкові поля:

• name — Зрозуміла для людини назва інстансу.

• target — Регіон, наприклад us-east або eu-de.

• resource_plan_id — План для цього інстансу. Дивись таблицю ID планів.

• resource_group — Група ресурсів, яку слід використати.

Ти також можеш включити об'єкт parameters, щоб встановити специфічні для квантових обчислень значення:

• instance_limit_seconds — Ціле число, або null. Ліміт часу використання для інстансу. Дивись Встановлення лімітів розподілу інстансу.

• usage_allocation_seconds — Ціле число, або null. Час, виділений цьому інстансу, який використовується планувальником справедливого розподілу для визначення пріоритету в черзі. Дивись Встановлення лімітів розподілу інстансу. Не застосовується до інстансів Pay-As-You-Go.

• backends — Масив рядків. Список дозволених імен бекендів, доступних для цього інстансу. ["ANY"] означає, що всі бекенди на плані доступні. [] означає, що жодні бекенди не доступні.

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 на інстансі

Використовуй ці інструкції, щоб налаштувати доступ до Qiskit Functions на існуючому інстансі IBM Quantum Compute Service за допомогою API IBM Cloud Resource Controller. Виконуй інструкції по порядку, оскільки команди спираються одна на одну. Наприклад, змінні, такі як токен та URL, встановлюються на одному кроці й повторно використовуються на наступних.

Передумови

• Ключ API IBM Cloud (також званий токеном). За потреби створи свій ключ API на панелі керування.

• CRN інстансу, який ти хочеш налаштувати. CRN інстансу вказано на твоїй сторінці Instances.

Крок 1: Отримання токена-носія

Обміняй свій ключ API на токен-носій. Ти передаватимеш цей токен у заголовку авторизації всіх запитів до resource controller. Виконай наступний код, щоб згенерувати токен-носій:

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) 

Відповідь включає поле access_token, яке є твоїм bearer-токеном. Скопіюй це значення.

Крок 2: Перевірка доступу

Перш ніж вносити будь-які зміни, підтверди, що твій токен працює, і перевір поточну конфігурацію інстансу.

cURL

Важливо

CRN має бути вручну закодований у форматі URL у шляху. Заміни кожен : на %3A, а кожен / на %2F. Наприклад, crn:v1:bluemix:... стає 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>"
# CRN буде закодований у форматі URL у шлях.
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"])

Відповідь 200 OK підтверджує, що твій токен дійсний. Поточна конфігурація інстансу знаходиться в полі extensions відповіді. Використовуй його замість parameters, яке може бути застарілим.

Крок 3: Пошук конфігурації функцій на рівні облікового запису

Інстансу може бути надано доступ лише до того, на що має право обліковий запис. Перш ніж налаштовувати інстанс, знайди конфігурацію облікового запису, щоб знати, які функції, бізнес-моделі та дозволи доступні для надання. Це джерело істини для значень, які ти надсилатимеш на кроці 4.

Виклич GET /accounts/{id} в API Qiskit Runtime зі своїм ключем API. {id} — це ID твого облікового запису без префікса a/. Ти можеш знайти його в 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"))

Кожен план у відповіді включає масив functions і, якщо налаштовано, об'єкт custom_functions. Вони перелічують точну назву, постачальника, бізнес-модель та значення дозволів, які ти можеш надати інстансу в межах цього плану.

примітка

GET /accounts/{id} показує, що доступно для надання на рівні облікового запису. GET /functions (див. Перевірка результату) показує, що вже надано конкретному інстансу. Використовуй кінцеву точку account, щоб дізнатися допустимі значення, та кінцеву точку functions, щоб підтвердити результат.

Крок 4: Налаштування доступу до функцій

Онови інстанс, щоб надати доступ до Catalog Functions та Custom Functions.

Важливі примітки

• Значення name, provider та business_model у functions мають точно збігатися з записами, налаштованими на рівні облікового запису (див. попередній крок). Дозволи мають бути непорожньою підмножиною дозволів облікового запису для цієї функції. Аналогічно, custom_functions.permissions має бути непорожньою підмножиною дозволів custom_functions облікового запису.
• Включай мітку часу в parameters у кожному PATCH. Resource Controller дедуплікує запити PATCH, порівнюючи вхідні parameters з останнім збереженим значенням. Якщо вони збігаються, запит мовчки відкидається з 200 OK, не досягаючи сервісу. Включай змінне значення мітки часу, щоб цього уникнути.

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

# Змінна мітка часу не дає Resource Controller дедуплікувати запит.
_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"])

Відповідь 200 OK вказує на успіх. Оновлена конфігурація з'являється в полі extensions відповіді.

Видалення доступу до функцій

Catalog Functions

Щоб видалити Catalog Functions з інстансу, надішли PATCH з "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()

Встановлення "functions": [] (порожній масив) еквівалентно очищує Catalog Functions. null є канонічною формою.

Custom Functions

Щоб видалити Custom Functions з інстансу, надішли PATCH з "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()

Встановлення "custom_functions": {"permissions": []} еквівалентно очищує custom functions. null є канонічною формою.

Перевірка результату

Щоб підтвердити, що інстанс має правильну конфігурацію Qiskit Functions, використовуй GET /functions з API Qiskit Runtime замість Resource Controller. Збережений стан Resource Controller може бути застарілим, якщо зміни на рівні облікового запису оновили інстанс поза межами 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

# Заголовок Service-CRN приймає необроблений CRN, а не форму, закодовану в 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())

Відповідь перелічує функції, до яких інстанс наразі має доступ.