Use a API do IBM Cloud Resource Controller para gerenciamento de instâncias

Você pode usar a API REST do IBM Cloud® Resource Controller para obter, criar e atualizar instâncias de forma programática.

Todos os endpoints do Resource Controller exigem que você se autentique passando um cabeçalho chamado Authorization com o token bearer. Consulte o guia de configuração da API REST.

Obter uma instância

Use o endpoint GET /v2/resource_instances/{crn} para obter informações sobre uma instância específica. O CRN deve estar codificado em URL no caminho.

Além dos campos padrão do Resource Controller, a resposta inclui campos específicos de quantum tanto em parameters quanto em extensions. extensions armazena os metadados normalizados da instância, enquanto parameters armazena apenas a solicitação mais recente para modificar a instância. Portanto, você deve ler a partir de extensions em vez de parameters.

O objeto extensions inclui estes campos:

instance_limit_seconds — Inteiro, ou null. O limite de tempo de uso da instância. Consulte Definir limites de alocação de instância.
usage_allocation_seconds — Inteiro, ou null. O tempo alocado para esta instância, usado pelo escalonador de compartilhamento justo para determinar a prioridade na fila. Consulte Definir limites de alocação de instância.
backends — Array de strings. A lista de permissões dos nomes de backends disponíveis para esta instância. ["ANY"] significa que todos os backends do plano estão disponíveis (o padrão). [] significa que nenhum backend está disponível.

O campo backends pode estar desatualizado

O campo backends no objeto extensions pode estar desatualizado. Isso pode acontecer quando o Suporte do IBM Quantum altera sua conta de uma forma que afeta as instâncias. Por exemplo, quando um backend é removido de uma conta, isso atualizará o backends da instância, mas essa alteração atualmente ainda não está refletida na API do Resource Controller.

Em vez disso, a solução alternativa atual é usar a API REST do IBM Quantum Compute Service com o endpoint GET /v1/backends. (Certifique-se de definir o cabeçalho Service-CRN com o CRN da sua instância.)

cURL
Python

O CRN deve estar codificado em URL no caminho. Substitua cada : por %3A e cada / por %2F. Por exemplo, crn:v1:bluemix:... se torna 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>"
# Usamos urllib.parse.quote para codificar o CRN em 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())

Obter uma lista de todas as instâncias

Use o endpoint GET /v2/resource_instances para obter uma lista de todas as suas instâncias. Defina o parâmetro de consulta resource_id como b6049020-80f4-11eb-a0f7-e35ec9b4054f para filtrar as instâncias do IBM Quantum®.

Se sua conta tiver vários planos e você quiser filtrar por plano, defina o parâmetro de consulta resource_plan_id como um dos seguintes valores:

Plano	`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 inclui o mesmo campo extensions descrito em Obter uma instância.

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

Atualizar uma instância

Use o endpoint PATCH /v2/resource_instances/{crn} para atualizar o limite, a alocação e os backends permitidos para uma instância. O CRN deve estar codificado em URL no caminho.

Passe um objeto JSON parameters no corpo da solicitação com os campos que deseja alterar, juntamente com o cabeçalho "Content-Type: application/json". Os campos omitidos permanecem inalterados.

instance_limit_seconds — Inteiro, ou null. O limite de tempo de uso da instância. Consulte Definir limites de alocação de instância.
usage_allocation_seconds — Inteiro, ou null. O tempo alocado para esta instância, usado pelo escalonador de compartilhamento justo para determinar a prioridade na fila. Consulte Definir limites de alocação de instância. Não aplicável a instâncias Pay-As-You-Go.
backends — Array de strings. A lista de permissões dos nomes de backends disponíveis para esta instância. ["ANY"] significa que todos os backends do plano estão disponíveis. [] significa que nenhum backend está disponível.

Sempre inclua um timestamp exclusivo

A API ignora silenciosamente a solicitação se parameters for idêntico à solicitação anterior. No objeto parameters, sempre inclua um campo timestamp definido para a hora atual, para que cada solicitação seja tratada como exclusiva.

A resposta do endpoint é semelhante à de obter uma instância, incluindo a forma como ela lida com o objeto extensions.

cURL
Python

O CRN deve estar codificado em URL no caminho. Substitua cada : por %3A e cada / por %2F. Por exemplo, crn:v1:bluemix:... se torna 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>"
# Usamos urllib.parse.quote para codificar o CRN em 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())

Criar uma nova instância

Use o endpoint POST /v2/resource_instances para criar (provisionar) uma nova instância. Passe um corpo JSON com o cabeçalho "Content-Type: application/json".

Campos obrigatórios:

name — Um nome legível para a instância.
target — A região, como us-east ou eu-de.
resource_plan_id — O plano desta instância. Consulte a tabela de IDs de plano.
resource_group — O grupo de recursos a ser usado.

Você também pode incluir um objeto parameters para definir valores específicos de quantum:

instance_limit_seconds — Inteiro, ou null. O limite de tempo de uso da instância. Consulte Definir limites de alocação de instância.
usage_allocation_seconds — Inteiro, ou null. O tempo alocado para esta instância, usado pelo escalonador de compartilhamento justo para determinar a prioridade na fila. Consulte Definir limites de alocação de instância. Não aplicável a instâncias Pay-As-You-Go.
backends — Array de strings. A lista de permissões dos nomes de backends disponíveis para esta instância. ["ANY"] significa que todos os backends do plano estão disponíveis. [] significa que nenhum backend está disponível.

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

Configurar acesso ao Qiskit Functions em uma instância

Use estas instruções para configurar o acesso ao Qiskit Functions em uma instância existente do IBM Quantum Compute Service usando a API do IBM Cloud Resource Controller. Siga as instruções na ordem, pois os comandos se baseiam uns nos outros. Por exemplo, variáveis como o token e a URL são definidas em uma etapa e reutilizadas nas etapas posteriores.

Pré-requisitos

Uma chave de API do IBM Cloud (também chamada de token). Se necessário, crie sua chave de API no painel.
O CRN da instância que você deseja configurar. O CRN da instância está listado na sua página de Instâncias.

Etapa 1: Obter um token bearer

Troque sua chave de API por um token bearer. Você passará esse token no cabeçalho de autorização de todas as solicitações do resource controller. Execute o código a seguir para gerar um token bearer:

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) 

A resposta inclui um campo access_token, que é o seu token bearer. Copie esse valor.

Etapa 2: Verificar o acesso

Antes de fazer qualquer alteração, confirme que seu token funciona e inspecione a configuração atual da instância.

cURL
Python

Importante

O CRN deve ser codificado manualmente em URL no caminho. Substitua cada : por %3A e cada / por %2F. Por exemplo, crn:v1:bluemix:... se torna 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>"
# O CRN será codificado em URL no caminho.
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"])

Uma resposta 200 OK confirma que seu token é válido. A configuração atual da instância está no campo extensions da resposta. Use isso em vez de parameters, que pode estar desatualizado.

Etapa 3: Consultar a configuração de funções em nível de conta

Uma instância só pode receber acesso ao que a conta tem direito. Antes de configurar a instância, consulte a configuração da conta para saber quais funções, modelos de negócios e permissões estão disponíveis para conceder. Esta é a fonte de verdade para os valores que você enviará na Etapa 4.

Chame GET /accounts/{id} na API do Qiskit Runtime com sua chave de API. O {id} é o ID da sua conta sem o prefixo a/. Você pode encontrá-lo a partir do CRN da instância (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"))

Cada plano na resposta inclui um array functions e, se configurado, um objeto custom_functions. Eles listam o nome exato, o provedor, o modelo de negócios e os valores de permissões que você pode conceder a uma instância nesse plano.

nota

GET /accounts/{id} mostra o que está disponível para conceder no nível da conta. GET /functions (consulte Verificar o resultado) mostra o que já foi concedido a uma instância específica. Use o endpoint account para descobrir valores válidos e o endpoint functions para confirmar o resultado.

Etapa 4: Configurar o acesso a funções

Atualize a instância para conceder acesso ao Catalog Functions e ao Custom Functions.

Notas importantes

Os valores name, provider e business_model em functions devem corresponder exatamente às entradas configuradas no nível da conta (consulte a etapa anterior). As permissões devem ser um subconjunto não vazio das permissões da conta para essa função. Da mesma forma, custom_functions.permissions deve ser um subconjunto não vazio das permissões custom_functions da conta.
Inclua um timestamp em parameters em cada PATCH. O Resource Controller deduplica solicitações PATCH comparando os parameters recebidos com o último valor armazenado. Se corresponderem, a solicitação é descartada silenciosamente com 200 OK sem chegar ao serviço. Inclua um valor de timestamp variável para evitar isso.

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

# Um timestamp variável impede que o Resource Controller deduplique a solicitação.
_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"])

Uma resposta 200 OK indica sucesso. A configuração atualizada aparece no campo extensions da resposta.

Remover o acesso a funções

Catalog Functions

Para remover o Catalog Functions de uma instância, envie um PATCH com "functions": null:

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

Definir "functions": [] (um array vazio) também limpa o Catalog Functions de forma equivalente. null é a forma canônica.

Custom Functions

Para remover o Custom Functions de uma instância, envie um PATCH com "custom_functions": null:

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

Definir "custom_functions": {"permissions": []} também limpa as funções personalizadas de forma equivalente. null é a forma canônica.

Verificar o resultado

Para confirmar que a instância tem a configuração correta do Qiskit Functions, use GET /functions na API do Qiskit Runtime em vez do Resource Controller. O estado armazenado do Resource Controller pode estar desatualizado se alterações no nível da conta atualizaram a instância fora do 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>'

# O cabeçalho Service-CRN usa o CRN bruto, não a forma codificada em 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())

A resposta lista as funções às quais a instância atualmente tem acesso.

Obter uma instância​

Obter uma lista de todas as instâncias​

Atualizar uma instância​

Criar uma nova instância​

Configurar acesso ao Qiskit Functions em uma instância​

Pré-requisitos​

Etapa 1: Obter um token bearer​

Etapa 2: Verificar o acesso​

Etapa 3: Consultar a configuração de funções em nível de conta​

Etapa 4: Configurar o acesso a funções​

Remover o acesso a funções​

Catalog Functions​

Custom Functions​

Verificar o resultado​