Aller au contenu
Vérifié

Connecter un domaine

Faites pointer l'un des domaines du compte vers le projet de cette clé via le DNS, avec une clé limitée à une application.

agent_domain_connect est un appel limité à un projet : contrairement à toutes les autres écritures de cette section, il ne prend pas d'app_id. Le projet vers lequel il pointe un domaine est celui dont la clé API elle-même a été créée : cette recette exige donc une clé Application (créée depuis l'onglet API d'un projet), pas une clé de Compte. agent_domain_list est la lecture complémentaire, les domaines du compte, pour que vous envoyiez toujours un nom que le compte possède réellement.

Méthodes

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.

Il faut une clé Application, pas une clé de Compte

Les deux méthodes résolvent uid à partir de la clé que vous envoyez, comme partout ailleurs, mais agent_domain_connect résout aussi app_id à partir d'elle, et seule une clé créée depuis l'onglet API d'un projet en porte un. Appelez-la avec une clé de Compte et elle répond -1, 'no app is bound to this action', avant même de regarder le domaine. Consultez Authentification pour les trois portées de clé.

Pas à pas

Lister les domaines du compte

Aucun champ en dehors de votre clé. Chaque ligne est un domaine que le compte a enregistré via Xuda ou connecté en déléguant ses serveurs de noms, quel que soit le projet (s'il y en a un) vers lequel il pointe actuellement, avec son propre 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. En pointer un vers le projet de cette clé

domain doit être l'un des noms que l'appel précédent a renvoyés. subdomain est facultatif et sans rapport avec le nom du projet de la clé d'application : c'est une étiquette sur le domaine ("app" pour app.example.com) ; omettez-le pour pointer plutôt l'apex du domaine. Relancer l'appel avec un autre subdomain ne perturbe pas un nom d'hôte que vous avez déjà attaché : seul l'enregistrement de ce nom d'hôte précis est remplacé.

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 réponse

agent_domain_list réduit chaque document de domaine enregistré à quatre champs :

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 vaut registered pour un domaine acheté via Xuda (Xuda est le bureau d'enregistrement et le DNS) ou connected pour un domaine enregistré ailleurs dont les serveurs de noms sont délégués à Xuda (DNS seulement, l'enregistrement reste où il était). Les deux fonctionnent de la même façon pour agent_domain_connect.

agent_domain_connect répond avec l'enregistrement DNS qu'elle a réellement écrit :

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

type dépend du genre de projet auquel la clé est limitée, pas de ce que vous envoyez : un projet VPS reçoit un enregistrement A vers son IP (ou AAAA sur une VM de ferme sans IPv4 publique), tout le reste reçoit un CNAME vers l'URL d'accès propre du projet. Chaque enregistrement passe par le proxy Cloudflare (proxied: true), donc le visiteur obtient du HTTPS en périphérie dans les deux cas. ssl_mode n'est défini que sur la voie VPS, où Xuda sonde aussi et définit le mode SSL d'origine de la zone (full, strict ou flexible) ; il revient à null pour une cible CNAME, le Universal SSL propre à Cloudflare couvrant ce cas sans réglage de zone à signaler.

Erreurs

Suite