Vai al contenuto
Verificata

Collegare un dominio

Punta via DNS uno dei domini dell'account al progetto di questa chiave, con una chiave limitata all'app.

agent_domain_connect è una chiamata limitata al progetto: a differenza di ogni altra scrittura di questa sezione, non accetta app_id. Il progetto a cui punta un dominio è quello da cui è stata creata la chiave API stessa, quindi questa ricetta richiede una chiave App (creata dalla scheda API del progetto), non una chiave Account. agent_domain_list è la lettura complementare, i domini dell'account, così invii sempre un nome che l'account possiede davvero.

Metodi

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.

Serve una chiave App, non una chiave Account

Entrambi i metodi ricavano uid dalla chiave che invii, come ovunque, ma agent_domain_connect ricava da essa anche app_id, e solo una chiave creata dalla scheda API di un progetto ne porta uno. Se la chiami con una chiave Account risponde -1, 'no app is bound to this action', prima ancora di guardare il dominio. Vedi Autenticazione per i tre ambiti delle chiavi.

Procedura

Elenca i domini dell'account

Nessun campo oltre alla tua chiave. Ogni riga è un dominio che l'account ha registrato tramite Xuda o collegato delegando i propri nameserver, a prescindere dal progetto (se ce n'è uno) a cui punta in questo momento, con il proprio 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. Punta un dominio al progetto di questa chiave

domain deve essere uno dei nomi restituiti dalla chiamata precedente. subdomain è facoltativo e non ha relazione con il nome del progetto della chiave app: è un'etichetta sul dominio ("app" per app.example.com); omettilo per puntare invece l'apex del dominio. Rieseguire questa chiamata con un subdomain diverso non tocca un hostname già collegato: viene sostituito solo il record di quell'hostname esatto.

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

La risposta

agent_domain_list riduce ogni documento di dominio salvato a quattro campi:

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 per un dominio acquistato tramite Xuda (Xuda è registrar e DNS) oppure connected per uno registrato altrove con i nameserver delegati a Xuda (solo DNS, la registrazione resta dov'era). Entrambi funzionano allo stesso modo per agent_domain_connect.

agent_domain_connect risponde con il record DNS che ha effettivamente scritto:

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

type dipende dal tipo di progetto a cui è legata la chiave, non da qualcosa che invii: un progetto VPS ottiene un record A verso il suo IP (oppure AAAA su una VM farm senza IPv4 pubblico), tutto il resto ottiene un CNAME verso l'URL di accesso del progetto. Ogni record passa dal proxy di Cloudflare (proxied: true), quindi il visitatore ottiene HTTPS al margine in ogni caso. ssl_mode viene impostato solo sul percorso VPS, dove Xuda verifica e imposta anche la modalità SSL di origine della zona (full, strict o flexible); torna null per una destinazione CNAME, dove Universal SSL di Cloudflare copre il caso senza un'impostazione di zona da riportare.

Errori

Passi successivi