Saltar para o conteúdo
Verificado

Ligar um domínio

Aponte um dos domínios da própria conta para o projeto desta chave através de DNS, com uma chave com âmbito de App.

agent_domain_connect é uma chamada com âmbito de projeto: ao contrário de todas as outras escritas desta secção, não recebe app_id. O projeto para o qual aponta um domínio é aquele a partir do qual a própria chave de API foi criada, por isso esta receita precisa de uma chave de App (criada no separador API do próprio projeto), não de uma chave de Conta. agent_domain_list é a leitura complementar, os domínios da própria conta, para que envie sempre um nome que a conta realmente possui.

Métodos

POST/cpi/agent_domain_list
user

Domains: list

List the account's registered domains (name, status, which app each is attached to). Use this BEFORE asking the user to type a domain: if they say 'connect one of my domains', call this and present the options.

POST/cpi/agent_domain_connect
user

Domains: connect to this VPS

Point one of the account's own domains (from agent_domain_list) at THIS project's VPS via DNS. Optional subdomain (e.g. 'app' -> app.example.com); omit to use the apex. Prefer a subdomain unless the user explicitly wants the apex. Attaching replaces any existing record on that exact hostname.

Isto precisa de uma chave de App, não de uma chave de Conta

Ambos os métodos resolvem o uid a partir da chave que envia, como em todo o lado, mas agent_domain_connect resolve também o app_id a partir dela, e só uma chave criada a partir do separador API de um projeto o traz. Chame-o com uma chave de Conta e responde -1, 'no app is bound to this action', antes de sequer olhar para o domínio. Consulte Autenticação para ver os três âmbitos de chave.

Passo a passo

Liste os domínios da conta

Sem campos além da sua chave. Cada linha é um domínio que a conta registou através da Xuda ou ligou delegando os seus servidores de nomes, o projeto para o qual aponta atualmente (se algum) e o seu próprio status.

curl -s https://xuda.ai/cpi/agent_domain_list \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY"}'
const res = await fetch('https://xuda.ai/cpi/agent_domain_list', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ api_key: 'YOUR_API_KEY' }),
});
const { code, data } = await res.json();
if (code > 0) for (const d of data.domains) console.log(d.domain, d.status, d.attached_app_id);
import requests

res = requests.post(
    'https://xuda.ai/cpi/agent_domain_list',
    json={'api_key': 'YOUR_API_KEY'},
)
body = res.json()
if body['code'] > 0:
    for d in body['data']['domains']:
        print(d['domain'], d['status'], d['attached_app_id'])

2. Aponte um para o projeto desta chave

domain tem de ser um dos nomes que a chamada anterior devolveu. subdomain é opcional e não tem relação com o nome do projeto da própria chave de app, é uma etiqueta no domínio ("app" para app.example.com); omita-o para apontar antes o apex do domínio. Voltar a executar isto com um subdomain diferente não perturba um nome de anfitrião que já tenha associado, apenas o registo desse nome exato é substituído.

curl -s https://xuda.ai/cpi/agent_domain_connect \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_APP_API_KEY","domain":"example.com","subdomain":"app"}'
const res = await fetch('https://xuda.ai/cpi/agent_domain_connect', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_APP_API_KEY',
    domain: 'example.com',
    subdomain: 'app',
  }),
});
const { code, data } = await res.json();
if (code > 0) console.log(data.record.type, data.record.name, data.record.target);
import requests

res = requests.post(
    'https://xuda.ai/cpi/agent_domain_connect',
    json={'api_key': 'YOUR_APP_API_KEY', 'domain': 'example.com', 'subdomain': 'app'},
)
body = res.json()
if body['code'] > 0:
    print(body['data']['record']['type'], body['data']['record']['name'], body['data']['record']['target'])

A resposta

agent_domain_list reduz cada documento de domínio guardado a quatro campos:

json
{
  "code": 1,
  "data": {
    "count": 2,
    "domains": [
      {
        "domain": "example.com",
        "status": "active",
        "connection_type": "registered",
        "attached_app_id": null
      },
      {
        "domain": "example.org",
        "status": "active",
        "connection_type": "connected",
        "attached_app_id": "app_5d9e21"
      }
    ]
  }
}

connection_type é registered para um domínio comprado através da Xuda (a Xuda é o registador e o DNS) ou connected para um registado noutro local com os servidores de nomes delegados na Xuda (só DNS, o registo fica onde estava). Ambos funcionam da mesma forma para agent_domain_connect.

agent_domain_connect responde com o registo DNS que realmente escreveu:

json
{
  "code": 1,
  "data": {
    "ok": true,
    "record": {
      "type": "A",
      "name": "app.example.com",
      "target": "203.0.113.42",
      "proxied": true,
      "ssl_mode": "full"
    }
  }
}

type depende do tipo de projeto a que a chave está associada, não de nada que envie: um projeto VPS recebe um registo A para o seu IP (ou AAAA numa VM de farm sem IPv4 público), tudo o resto recebe um CNAME para o URL de acesso do próprio projeto. Todos os registos passam pelo proxy da Cloudflare (proxied: true), por isso o visitante recebe HTTPS na periferia em qualquer dos casos. ssl_mode só é definido no caminho VPS, em que a Xuda também sonda e define o modo SSL de origem da zona (full, strict ou flexible); regressa null para um destino CNAME, o Universal SSL da própria Cloudflare cobre esse caso sem uma definição de zona a reportar.

Erros

A seguir