Zum Inhalt springen
Geprüft

Eine Domain verbinden

Richte eine der eigenen Domains des Kontos per DNS auf das Projekt dieses Schlüssels, mit einem App-Schlüssel.

agent_domain_connect ist ein projektbezogener Aufruf: Anders als jeder andere Schreibzugriff in diesem Abschnitt nimmt er kein app_id. Das Projekt, auf das er eine Domain richtet, ist dasjenige, aus dem der API-Schlüssel selbst erstellt wurde. Dieses Rezept braucht also einen App-Schlüssel (erstellt im eigenen API-Tab eines Projekts), keinen Konto- Schlüssel. agent_domain_list ist der zugehörige Lesezugriff auf die eigenen Domains des Kontos, damit du immer einen Namen sendest, den das Konto tatsächlich besitzt.

Methoden

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.

Das braucht einen App-Schlüssel, keinen Konto-Schlüssel

Beide Methoden lösen uid aus dem gesendeten Schlüssel auf, wie überall sonst, aber agent_domain_connect löst auch app_id daraus auf, und nur ein Schlüssel aus dem API-Tab eines Projekts trägt eines. Rufst du sie mit einem Konto-Schlüssel auf, antwortet sie -1, 'no app is bound to this action', bevor sie die Domain überhaupt ansieht. Die drei Schlüssel-Geltungsbereiche findest du unter Authentifizierung.

Schritt für Schritt

Die Domains des Kontos auflisten

Keine Felder außer deinem Schlüssel. Jede Zeile ist eine Domain, die das Konto über Xuda registriert oder durch Delegieren ihrer Nameserver verbunden hat, mit dem Projekt, auf das sie gerade zeigt (falls vorhanden), und ihrem eigenen 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. Eine auf das Projekt dieses Schlüssels richten

domain muss einer der Namen sein, die der vorige Aufruf zurückgegeben hat. subdomain ist optional und hat nichts mit dem eigenen Projektnamen des App-Schlüssels zu tun, es ist ein Label an der Domain ("app" für app.example.com). Lass es weg, um stattdessen den Apex der Domain zu richten. Wenn du das mit einer anderen subdomain erneut ausführst, bleibt ein bereits verbundener Hostname unberührt, nur der Eintrag genau dieses Hostnamens wird ersetzt.

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

Die Antwort

agent_domain_list kürzt jedes gespeicherte Domain-Dokument auf vier Felder:

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 ist registered für eine über Xuda gekaufte Domain (Xuda ist Registrar und DNS) oder connected für eine anderswo registrierte, deren Nameserver an Xuda delegiert sind (nur DNS, die Registrierung bleibt dort, wo sie war). Beide funktionieren bei agent_domain_connect gleich.

agent_domain_connect antwortet mit dem DNS-Eintrag, den es tatsächlich geschrieben hat:

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

type hängt davon ab, welche Art von Projekt der Schlüssel zugeordnet ist, nicht von etwas, das du sendest: Ein VPS- Projekt bekommt einen A-Eintrag auf seine IP (oder AAAA bei einer Farm-VM ohne öffentliche IPv4), alles andere bekommt einen CNAME auf die eigene Zugriffs-URL des Projekts. Jeder Eintrag läuft über den Cloudflare-Proxy (proxied: true), daher bekommt der Besucher in beiden Fällen HTTPS am Edge. ssl_mode wird nur beim VPS-Pfad gesetzt, wo Xuda außerdem den Origin-SSL-Modus der Zone prüft und setzt (full, strict oder flexible). Bei einem CNAME-Ziel kommt es null zurück, da Cloudflares eigenes Universal SSL diesen Fall abdeckt, ohne dass eine Zoneneinstellung zu melden wäre.

Fehler

Weiter