인스턴스 관리를 위해 IBM Cloud Resource Controller API 사용

IBM Cloud® Resource Controller REST API를 사용하여 프로그래밍 방식으로 인스턴스를 가져오고, 생성하고, 업데이트할 수 있습니다.

모든 Resource Controller 엔드포인트는 베어러 토큰과 함께 Authorization이라는 헤더를 전달하여 인증해야 합니다. REST API 설정 가이드를 참조하세요.

인스턴스 가져오기

특정 인스턴스에 대한 정보를 가져오려면 GET /v2/resource_instances/{crn} 엔드포인트를 사용하세요. CRN은 경로에서 URL 인코딩되어야 합니다.

표준 Resource Controller 필드 외에도, 응답에는 parameters와 extensions 모두에 양자 관련 필드가 포함됩니다. extensions는 인스턴스의 정규화된 메타데이터를 저장하는 반면, parameters는 인스턴스를 수정하기 위한 가장 최근 요청만 저장합니다. 따라서 parameters가 아닌 extensions에서 읽어야 합니다.

extensions 객체에는 다음 필드가 포함됩니다:

instance_limit_seconds — 정수 또는 null. 인스턴스의 사용 시간 제한입니다. 인스턴스 할당 한도 설정을 참조하세요.
usage_allocation_seconds — 정수 또는 null. 이 인스턴스에 할당된 시간으로, 공정 분배 스케줄러가 큐 우선순위를 결정하는 데 사용됩니다. 인스턴스 할당 한도 설정을 참조하세요.
backends — 문자열 배열. 이 인스턴스에서 사용 가능한 Backend 이름의 허용 목록입니다. ["ANY"]는 플랜의 모든 Backend를 사용할 수 있음을 의미합니다(기본값). []는 사용 가능한 Backend가 없음을 의미합니다.

backends 필드가 오래되었을 수 있습니다

extensions 객체의 backends 필드는 오래되었을 수 있습니다. 이는 IBM Quantum Support가 인스턴스에 영향을 미치는 방식으로 계정을 변경할 때 발생할 수 있습니다. 예를 들어, 계정에서 Backend가 제거되면 인스턴스의 backends가 업데이트되지만, 이 변경 사항은 현재 Resource Controller API에 아직 반영되지 않습니다.

대신, 현재 우회 방법은 GET /v1/backends 엔드포인트와 함께 IBM Quantum Compute Service REST API를 사용하는 것입니다. (Service-CRN 헤더를 인스턴스의 CRN으로 설정했는지 확인하세요.)

cURL
Python

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>'

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 엔드포인트를 사용하세요. IBM Quantum® 인스턴스로 필터링하려면 resource_id 쿼리 파라미터를 b6049020-80f4-11eb-a0f7-e35ec9b4054f로 설정하세요.

계정에 여러 플랜이 있고 플랜별로 필터링하려면, 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
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())

인스턴스 업데이트

인스턴스의 한도, 할당 및 허용된 Backend를 업데이트하려면 PATCH /v2/resource_instances/{crn} 엔드포인트를 사용하세요. CRN은 경로에서 URL 인코딩되어야 합니다.

변경하려는 필드가 포함된 parameters JSON 객체를 "Content-Type: application/json" 헤더와 함께 요청 본문에 전달하세요. 생략된 필드는 변경되지 않은 상태로 유지됩니다.

instance_limit_seconds — 정수 또는 null. 인스턴스의 사용 시간 제한입니다. 인스턴스 할당 한도 설정을 참조하세요.
usage_allocation_seconds — 정수 또는 null. 이 인스턴스에 할당된 시간으로, 공정 분배 스케줄러가 큐 우선순위를 결정하는 데 사용됩니다. 인스턴스 할당 한도 설정을 참조하세요. Pay-As-You-Go 인스턴스에는 적용되지 않습니다.
backends — 문자열 배열. 이 인스턴스에서 사용 가능한 Backend 이름의 허용 목록입니다. ["ANY"]는 플랜의 모든 Backend를 사용할 수 있음을 의미합니다. []는 사용 가능한 Backend가 없음을 의미합니다.

항상 고유한 타임스탬프를 포함하세요

parameters가 이전 요청과 동일하면 API는 요청을 무시합니다. parameters 객체에는 각 요청이 고유하게 처리되도록 현재 시간으로 설정된 timestamp 필드를 항상 포함하세요.

이 엔드포인트의 응답은 extensions 객체를 처리하는 방식을 포함하여 인스턴스 가져오기와 유사합니다.

cURL
Python

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
    }
}"

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 엔드포인트를 사용하세요. "Content-Type: application/json" 헤더와 함께 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 — 문자열 배열. 이 인스턴스에서 사용 가능한 Backend 이름의 허용 목록입니다. ["ANY"]는 플랜의 모든 Backend를 사용할 수 있음을 의미합니다. []는 사용 가능한 Backend가 없음을 의미합니다.

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

인스턴스에서 Qiskit Functions 액세스 구성

IBM Cloud Resource Controller API를 사용하여 기존 IBM Quantum Compute Service 인스턴스에서 Qiskit Functions 액세스를 구성하려면 다음 지침을 사용하세요. 명령이 서로를 기반으로 하므로 지침을 순서대로 따르세요. 예를 들어, 토큰 및 URL과 같은 변수는 한 단계에서 설정되어 이후 단계에서 재사용됩니다.

전제 조건

IBM Cloud API 키(토큰이라고도 함)입니다. 필요한 경우 대시보드에서 API 키를 생성하세요.
구성하려는 인스턴스의 CRN입니다. 인스턴스의 CRN은 인스턴스 페이지에 나열되어 있습니다.

1단계: 베어러 토큰 가져오기

API 키를 베어러 토큰으로 교환합니다. 이 토큰은 모든 resource controller 요청의 authorization 헤더에 전달합니다. 다음 코드를 실행하여 베어러 토큰을 생성하세요:

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) 

응답에는 베어러 토큰인 access_token 필드가 포함됩니다. 이 값을 복사하세요.

2단계: 액세스 확인

변경 작업을 하기 전에, 토큰이 작동하는지 확인하고 현재 인스턴스 구성을 검사하세요.

cURL
Python

중요

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>'

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단계: 계정 수준 Functions 구성 조회

인스턴스는 계정이 부여받은 권한 범위 내에서만 액세스를 부여받을 수 있습니다. 인스턴스를 구성하기 전에, 부여할 수 있는 Functions, 비즈니스 모델 및 권한을 알 수 있도록 계정의 구성을 조회하세요. 이는 4단계에서 전송할 값의 신뢰할 수 있는 원본입니다.

API 키로 Qiskit Runtime API에서 GET /accounts/{id}를 호출하세요. {id}는 a/ 접두사가 없는 계정 ID입니다. 인스턴스 CRN(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"))

응답의 각 플랜에는 functions 배열과, 구성된 경우 custom_functions 객체가 포함됩니다. 이는 해당 플랜에서 인스턴스에 부여할 수 있는 정확한 name, provider, business model 및 permissions 값을 나열합니다.

참고

GET /accounts/{id}는 계정 수준에서 부여할 수 있는 항목을 보여줍니다. GET /functions(결과 확인 참조)는 특정 인스턴스에 이미 부여된 항목을 보여줍니다. account 엔드포인트로 부여 가능한 유효한 값을 알아보고, functions 엔드포인트로 결과를 확인하세요.

4단계: Functions 액세스 구성

Catalog Functions 및 Custom Functions에 대한 액세스를 부여하도록 인스턴스를 업데이트합니다.

중요 참고 사항

functions의 name, provider, business_model 값은 계정 수준에서 구성된 항목과 정확히 일치해야 합니다(이전 단계 참조). Permissions는 해당 function에 대한 계정 권한의 비어 있지 않은 부분 집합이어야 합니다. 마찬가지로, custom_functions.permissions는 계정의 custom_functions 권한의 비어 있지 않은 부분 집합이어야 합니다.
모든 PATCH에서 parameters에 타임스탬프를 포함하세요. Resource Controller는 들어오는 parameters를 마지막으로 저장된 값과 비교하여 PATCH 요청의 중복을 제거합니다. 값이 일치하면 서비스에 도달하지 않고 200 OK로 요청이 조용히 무시됩니다. 이를 방지하려면 변경되는 타임스탬프 값을 포함하세요.

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

# 변경되는 타임스탬프는 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 필드에 표시됩니다.

Functions 액세스 제거

Catalog Functions

인스턴스에서 Catalog Functions를 제거하려면 "functions": null과 함께 PATCH를 전송하세요:

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

"functions": [](빈 배열)을 설정해도 동일하게 Catalog Functions가 지워집니다. null이 정식 형식입니다.

Custom Functions

인스턴스에서 Custom Functions를 제거하려면 "custom_functions": null과 함께 PATCH를 전송하세요:

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

"custom_functions": {"permissions": []}을 설정해도 동일하게 custom functions가 지워집니다. null이 정식 형식입니다.

결과 확인

인스턴스가 올바른 Qiskit Functions 구성을 갖고 있는지 확인하려면, Resource Controller 대신 Qiskit Runtime API의 GET /functions를 사용하세요. 계정 수준 변경으로 Resource Controller 외부에서 인스턴스가 업데이트된 경우, 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>'

# Service-CRN 헤더는 URL 인코딩된 형식이 아닌 원본 CRN을 사용합니다.
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())

응답에는 인스턴스가 현재 액세스할 수 있는 Functions가 나열됩니다.

인스턴스 가져오기​

모든 인스턴스 목록 가져오기​

인스턴스 업데이트​

새 인스턴스 생성​

인스턴스에서 Qiskit Functions 액세스 구성​

전제 조건​

1단계: 베어러 토큰 가져오기​

2단계: 액세스 확인​

3단계: 계정 수준 Functions 구성 조회​

4단계: Functions 액세스 구성​

Functions 액세스 제거​

Catalog Functions​

Custom Functions​

결과 확인​