Beispiele

Die nachfolgenden Beispiele dienen ausschließlich der prinzipiellen Veranschaulichung und haben keinen Anspruch auf Korrektheit. Sie sind daher inhaltlich als ungültig zu betrachten. Verbindliche Daten müssen über den Objekttyp- bzw. Funktionsindex der WebAPI abgefragt werden.

Hinweise:

  • Je nach Betriebssystem bzw. Kommandozeileninterpreter (Shell) wird der Backslash ‘\‘ als Shell-Escape-Character verwendet. Eine einfache Formatierung der JSON-Ausgabe mit Zeilenumbrüchen und Einrückungen erreicht man z.B. mit ‘curl … | python -m json.tool’.
  • Aus Sicherheitsgründen empfiehlt es sich, den Token-Text in einer curl-Konfigurationsdatei zu hinterlegen bzw. diese vorher entsprechend zu generieren. Der Token-Text sollte nicht direkt über die Kommandozeile übergeben werden.
  • Bei GET-Requests müssen Sonderzeichen [], {} in der Parameterzeichenkette (query string) entweder einen vorangestellten Backslash bekommen, oder man verwendet die curl-Option -g bzw. --globoff.

Indexabfragen

Die Indexabfragen erlauben es, die gültigen Wertebelegungen der jeweils nächsten Unterebene des URI-Schemas festzustellen.

Versionsindex

  • Ziel: Ausgabe der implementierten Versionen
  • Inhalt der curl-Konfigurationsdatei curl.cfg (Authentifizierung nicht erforderlich):
--url "https://api.netdb.scc.kit.edu"
--header "Content-Type: application/json"
  • Aufruf:
curl --config curl.cfg

Systemindex

  • Ziel: Ausgabe aller unter Version 4.0 implementierten Systeme
  • Inhalt der curl-Konfigurationsdatei curl.cfg (Authentifizierung nicht erforderlich):
--url "https://api.netdb.scc.kit.edu/4.0"
--header "Content-Type: application/json"
  • Aufruf:
curl --config curl.cfg

Objekttypindex

  • Ziel: Ausgabe der in Version 4.0 im System org implementierten Objekttypen
  • Inhalt der curl-Konfigurationsdatei curl.cfg (Authentifizierung nicht erforderlich):
--url "https://api.netdb.scc.kit.edu/4.0/org"
--header "Content-Type: application/json"
  • Aufruf:
curl --config curl.cfg

Funktionsindex

  • Ziel: Ausgabe der in Version 4.0 im System org und dem Objekttyp ou verfügbaren Funktionen
  • Inhalt der curl-Konfigurationsdatei curl.cfg (Authentifizierung nicht erforderlich):
--url "https://api.netdb.scc.kit.edu/4.0/org/unit"
--header "Content-Type: application/json"
  • Aufruf:
curl --config curl.cfg

Abfragen des Systemdatenverzeichnisses (Objekttypdaten)

  • Ziel: Ausgabe der Objektdaten für System wapi, Objekttyp object_type, Eingrenzung der Suche auf den Systemnamen “dns” und den Objekttypnamen “fqdn”
  • entspricht: Ausgabe der Objekttypdaten für System dns, Objekttyp fqdn
  • Inhalt der curl-Konfigurationsdatei curl.cfg (Authentifizierung nicht erforderlich):
--header "Content-Type: application/json"
  • Aufruf als GET-Request:
curl --globoff --config curl.cfg 'https://api.netdb.scc.kit.edu/4.0/wapi/object_type/list?system_list=["dns"]&name_list=["fqdn"]'
  • Gleichwertiger Aufruf als POST-Request:
curl --config curl.cfg -d '{"old": {"system_list": ["dns"], "name_list": ["fqdn"]}}' 'https://api.netdb.scc.kit.edu/4.0/wapi/object_type/list'

Abfragen des Systemdatenverzeichnisses (Funktionsdaten)

  • Ziel: Ausgabe der Objektdaten für System wapi, Objekttyp function, Eingrenzung der Suche auf den Systemnamen “dns”, den Objekttypnamen “fqdn” und den Funktionsnamen “create”
  • entspricht: Ausgabe der Parameterdaten für System dns, Objekttyp fqdn, Funktion create
  • Inhalt der curl-Konfigurationsdatei curl.cfg (Authentifizierung nicht erforderlich):
--header "Content-Type: application/json"
  • Aufruf als GET-Request:
curl --globoff --config curl.cfg 'https://api.netdb.scc.kit.edu/4.0/wapi/function/list?system_list=["dns"]&object_type_list=["fqdn"]&name_list=["create"]'
  • Gleichwertiger Aufruf als POST-Request:
curl --config curl.cfg -d '{"old": {"system_list": ["dns"], "object_type_list": ["fqdn"], "name_list": ["create"]}}' 'https://api.netdb.scc.kit.edu/4.0/wapi/function/list'

Objektabfragen

Einzelbefehls-Transaktion: FQDN-Ausgabe

  • Ziel: Ausgabe der Objektdaten für System dns, Objekttyp fqdn, Eingrenzung der Suche auf das Label-Muster ‘^host’ (als regulärer Ausdruck)
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf als GET-Request:
curl --globoff --config curl.cfg 'https://api.netdb.scc.kit.edu/4.0/dns/fqdn/list?label_regexp=^host.?$'
  • URI als POST-Request:
curl --config curl.cfg -d '{"old": {"label_regexp": "^host.?$"}}' 'https://api.netdb.scc.kit.edu/4.0/dns/fqdn/list'

Komplexe Transaktion: Verbund-Ausgabe mit Ref-InnerJOIN, ohne explizite Statement-Indizierung

  • Ziel: Die folgenden 7 Statements (mit Positionsangabe) liefern

    • [0]: alle eigenen Netzbereiche (BCDs)
    • [1]: alle Gruppenzuordnungen zu den Netzbereichen aus dem 0. Stmt.
    • [2]: alle Gruppen zu den Gruppenzuordnungen aus dem 1. Stmt.
    • [3]: alle Betreuerzuordnungen zu den Gruppen aus dem 2. Stmt.
    • [4]: alle Domainzuordnungen zu den Gruppen aus dem 2. Stmt.
    • [5]: alle neuesten Top-5-Eventlog-Records, die den Netzbereichen (BCD) aus dem 0. Stmt. zugeordnet sind (zeitlich absteigend je BCD)
    • [6]: alle ältesten Top-5-Eventlog-Records, die den Netzbereichen (BCD) aus dem 0. Stmt. zugeordnet sind (zeitlich aufsteigend je BCD)

  • Vorbereitung:

    • Als Statement-Index wird automatisch die Position eingesetzt. Referenzierende JOIN-Anweisungen müssen sich auf diese Position beziehen.
    • Bereitstellen des Request Body als JSON-Dokument (z.B. als Eingabedatei query_dns.json)
[
  {"name": "nd.bcd.list", "old": {"is_own": true}},
  {"name": "nd.bcd2group.list", "inner_join_ref": {"0": "default"}},
  {"name": "cntl.group.list", "inner_join_ref": {"1": "default"}},
  {"name": "cntl.mgr2group.list", "inner_join_ref": {"2": "default"}},
  {"name": "dns.fqdn2group.list", "inner_join_ref": {"2": "default"}},
  {"name": "evlog.record.list", "old": {"top_n": 5, "sorting_params_list": ["object_gfk", "ta_timestamp desc"]}, "inner_join_ref": {"0": null}},
  {"name": "evlog.record.list", "old": {"top_n": 5, "top_n_from_newest": false, "sorting_params_list": ["object_gfk", "ta_timestamp asc"]}, "inner_join_ref": {"0": null}}
]
  • generischer Transaktionsaufruf über /wapi/transaction/execute
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--url "https://api.netdb.scc.kit.edu/4.0/wapi/transaction/execute"
--data "@query_dns.json"
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf:
curl --config curl.cfg

Komplexe Transaktion: Verbund-Ausgabe mit Ref-InnerJOIN, mit expliziter Statement-Indizierung

  • Ziel: analog zum vorigen Beispiel
  • Vorbereitung:
    • Auswahl der Indexnamen für alle Statements, die referenziert werden (Pos. 0-2)
    • Einsetzen der Indexnamen in die referenzierenden JOIN-Anweisungen
    • Bereitstellen des Request Body als JSON-Dokument (z.B. als Eingabedatei query_dns.json)
[
  {"idx": "bcd", "name": "nd.bcd.list", "old": {"is_own": true}},
  {"idx": "b2g", "name": "nd.bcd2group.list", "inner_join_ref": {"bcd": "default"}},
  {"idx": "g", "name": "cntl.group.list", "inner_join_ref": {"b2g": "default"}},
  {"name": "cntl.mgr2group.list", "inner_join_ref": {"g": "default"}},
  {"name": "dns.fqdn2group.list", "inner_join_ref": {"g": "default"}},
  {"name": "evlog.record.list", "old": {"top_n": 5, "sorting_params_list": ["object_gfk", "ta_timestamp desc"]}, "inner_join_ref": {"bcd": null}},
  {"name": "evlog.record.list", "old": {"top_n": 5, "top_n_from_newest": false, "sorting_params_list": ["object_gfk", "ta_timestamp asc"]}, "inner_join_ref": {"bcd": null}}
]
  • generischer Transaktionsaufruf über /wapi/transaction/execute
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--url "https://api.netdb.scc.kit.edu/4.0/wapi/transaction/execute"
--data "@query_dns.json"
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf:
curl --config curl.cfg

Komplexe Transaktion: Verbund-Ausgabe mit Ref-InnerJOIN, explizite Statement-Indizierung und Constraint-Angabe; Filterung unbenötigter Objektattribute

  • Ziel: Die folgenden 3 Statements (mit Indexangabe) liefern

    • "rr_cname": alle eigenen CNAME-RRs
    • "fqdn_cname": alle Ziel-FQDNs zu den RRs via Stmt-Index “rr_cname”. Dieses Statement wird nur als Verbindung zwischen vorigem und nachfolgendem Statement benötigt, daher soll die Ausgabe komplett gefiltert werden.
    • "rr_target": alle Ziel-RRs zu den Owner-FQDNs via Stmt-Index “fqdn_cname”. In diesem Statement werden nur die Objektattribute fqdn, ttl, type, data benötigt.

  • Vorbereitung:

    • Auswahl der Indexnamen für alle Statements
    • Einsetzen der Indexnamen in die referenzierenden JOIN-Anweisungen
    • Ermitteln der Constraint-Namen unter Abfrage des Systemdatenbereichs für die relevanten Objekttypen dns.fqdn und dns.record, da es zwischen diesen beiden Objekkttypen 2 FK-Constraints (Typ F) gibt. Für die Ziel-FQDNs der RRs muss demnach "api_fkey_dns_record_target_fqdn" als Constraint eingesetzt werden; für die Owner-FQDNs kann "api_fkey_dns_record_fqdn" oder "default" eingesetzt werden.
    • Bereitstellen des Request Body als JSON-Dokument (z.B. als Eingabedatei query_dns.json)
[
  {"idx": "rr_cname", "name": "dns.record.list", "old": {"is_own": true, "type": "CNAME"}},
  {"idx": "fqdn_cname", "name": "dns.fqdn.list", "old": {"filter_params_dict": {"show": true, "attrs_list": null}}, "inner_join_ref": {"rr_cname": "api_fkey_dns_record_target_fqdn"}},
  {"idx": "rr_target", "name": "dns.record.list", "old": {"filter_params_dict": {"show": true, "attrs_list": ["fqdn","ttl","type","data"]}}, "inner_join_ref": {"fqdn_cname": "api_fkey_dns_record_fqdn"}}
]
  • generischer Transaktionsaufruf über /wapi/transaction/execute
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--url "https://api.netdb.scc.kit.edu/4.0/wapi/transaction/execute"
--data "@query_dns.json"
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf:
curl --config curl.cfg

Komplexe Transaktion: Verbund-Ausgabe mit verschiedenen JOIN-Anweisungen (1)

Die folgenden 3 Statements (mit Indexangabe) liefern

  • "fqdn": alle eigenen FQDNs
  • "fqdn: rrs nxst": alle FQDNs aus Stmt-Index “fqdn”, die nicht in RRs vorkommen.
  • "fqdn: rrs xst": alle FQDNs aus Stmt-Index “fqdn”, die in RRs vorkommen.
[
  {"idx": "fqdn", "name": "dns.fqdn.list", "old": {"is_own": true}},
  {"idx": "fqdn: rrs nxst", "name": "dns.fqdn.list", "inner_join_ref": {"fqdn": "self"}, "anti_join_noref": {"and": ["api_fkey_dns_record_fqdn"]}},
  {"idx": "fqdn: rrs xst", "name": "dns.fqdn.list", "inner_join_ref": {"fqdn": "self"}, "semi_join_noref": {"and": ["api_fkey_dns_record_fqdn"]}}
]

Komplexe Transaktion: Verbund-Ausgabe mit verschiedenen JOIN-Anweisungen (2)

Die folgenden 6 Statements (mit Indexangabe) liefern

  • "bcdcat": BCD-Kategorie ‘USER’
  • "bcd": alle BCDs, die zur Kategorie im Stmt-Index “bcdcat” gehören und die DHCP aktiviert haben
  • "bcd: nxst s or nxst v": alle BCDs aus Stmt-Index “bcd”, denen entweder kein Subnetz oder kein Vlan zugeordnet ist
  • "bcd: nxst s and nxst v": alle BCDs aus Stmt-Index “bcd”, denen weder ein Subnetz noch ein Vlan zugeordnet ist
  • "bcd: xst (s or v) and g": alle BCDs, die zur Kategorie im Stmt-Index “bcdcat” gehören und denen
    • entweder (mindestens) ein Subnetz oder (mindestens) ein Vlan zugeordnet ist sowie
    • (mindestens) eine Gruppe zugeordnet ist
  • "bcd: xst (s or v) and nxst g": alle BCDs, die zur Kategorie im Stmt-Index “bcdcat” gehören, nicht im Stmt-Index “bcd” vorkommen und denen
    • entweder (mindestens) ein Subnetz oder (mindestens) ein Vlan zugeordnet ist sowie
    • keine Gruppe zugeordnet ist
[
  {"idx": "bcdcat", "name": "ndcfg.bcd_categ.list", "old": {"name": "USER"}},
  {"idx": "bcd", "name": "nd.bcd.list", "old": {"dhcp_enabled": true}, "inner_join_ref": {"bcdcat": "default"}},
  {
    "idx": "bcd: nxst s or nxst v", "name": "nd.bcd.list", "inner_join_ref": {"bcd": "self"},
    "anti_join_noref": {"or": [ "api_fkey_nd_ip_subnet_bcd", "api_fkey_nd_vlan_bcd" ]}
  },
  {
    "idx": "bcd: nxst s and nxst v", "name": "nd.bcd.list", "inner_join_ref": {"bcd": "self"},
    "anti_join_noref": {"and": [ "api_fkey_nd_ip_subnet_bcd", "api_fkey_nd_vlan_bcd" ]}
  },
  {
    "idx": "bcd: xst (s or v) and g", "name": "nd.bcd.list", "inner_join_ref": {"bcdcat": "default"},
    "semi_join_noref":
      {
        "or": [ "api_fkey_nd_ip_subnet_bcd", "api_fkey_nd_vlan_bcd" ],
        "and": [ "api_fkey_nd_bcd2group_bcd" ]
      }
  },
  {
    "idx": "bcd: xst (s or v) and nxst g", "name": "nd.bcd.list", "anti_join_ref": {"bcd": "self"}, "inner_join_ref": {"bcdcat": "default"},
    "semi_join_noref": {"or": [ "api_fkey_nd_ip_subnet_bcd", "api_fkey_nd_vlan_bcd" ]},
    "anti_join_noref": {"and": [ "api_fkey_nd_bcd2group_bcd" ]}
  }
]

Komplexe Transaktion: Ausgabe globaler Objektattribute

Die folgenden 4 Statements (mit Indexangabe) liefern

  • "dev": einen Datensatz des Objekttyps nd.device (via Primärparameter "fqdn")
  • "otav": alle Objektattribute, die zum vorigen Objekt gehören
  • "otak": alle Objekttypattribute zum Stmt-Index “otav”
  • "otad": alle Objekttypattribut-Schüsselwortdefinitionen zum Stmt-Index “otak”
[
  {"idx": "dev", "name": "nd.device.list", "old": {"fqdn": "r-bb-wh.tmn.scc.kit.edu."}},
  {"idx": "otav", "name": "cntl.ot_attr_val.list", "inner_join_ref": {"dev": null}},
  {"idx": "otak", "name": "cntl.ot_attr_key.list", "inner_join_ref": {"otav": "default"}},
  {"idx": "otad", "name": "cntl.ot_attr_def.list", "inner_join_ref": {"otak": "default"}}
]

Komplexe Transaktion: Objektsuche über globale Objektattribute

Die folgenden 2 Statements (mit Indexangabe) liefern

  • "otav": alle Objektattribute zum Objekttyp nd.module mit dem Schlüsselwort "stack_pos" und mit Werten zwischen 2 und 4
  • "mdl2otav": alle Module, die zu den gefundenen Attributen aus dem Stmt-Index “otav” gehören
[
  {"idx": "otav", "name": "cntl.ot_attr_val.list", "old": {"object_type_fq_name": "nd.module", "ot_attr_def_key_word": "stack_pos", "value": 2, "value_operator": "int_range", "value_range": 4}},
  {"idx": "mdl2otav", "name": "nd.module.list", "inner_join_ref": {"otav": null}}
]

Objektmodifikationen

Einfache Dateneingabe durch eine Einzelbefehls-Transaktion mit nicht-leerer Antwort (dns.record.create)

  • Ziel: Anlegen eines DNS-A-Records eines RR-Sets (Satz von potenziell mehreren Records)
  • Vorbereitung: Bereitstellen des Request Body als JSON-Dokument (z.B. als Eingabedatei create_rr.json).
{
  "new": {
    "fqdn": "myhost.kit.test",
    "fqdn_description": "blubb",
    "target_is_reverse_unique": false,
    "target_is_singleton": false,
    "type": "A",
    "data": "192.168.1.1"
  }
}
  • Die in obiger Datei nicht enthaltenen, aber erforderlichen Daten für System, Objekttyp und Funktion werden in der URI-Adresse übergeben
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--url "https://api.netdb.scc.kit.edu/4.0/dns/record/create"
--data "@create_rr.json"
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf:
curl --config curl.cfg

Einfache Dateneingabe durch eine Einzelbefehls-Transaktion mit nicht-leerer Antwort (dns.record.imp)

  • Ziel: Importieren der RR-Sätze zu einem FQDN
  • Vorbereitung: Bereitstellen des Request Body als JSON-Dokument (z.B. als Eingabedatei import_rr.json).
{
  "new": {
    "fqdn": "myhost.kit.test",
    "fqdn_description": "hello world!",
    "import_data": {
      "dns.record_imp": [
        {"type": "A", "target_is_reverse_unique": false, "data_list": ["192.168.1.1"]},
        {"type": "AAAA", "target_is_reverse_unique": true, "target_is_singleton": false, "data_list": ["abcd::1", "abcd::2"]},
        {"type": "TXT", "data_list": ["\"textpart_in_same_rr_1\" \"textpart_in_same_rr_2\""]},
        {"type": "MX", "data_list": ["10 mail.kit.test"] }
      ]
    }
  }
}
  • Die in obiger Datei nicht enthaltenen, aber erforderlichen Daten für System, Objekttyp und Funktion werden in der URI-Adresse übergeben
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--url "https://api.netdb.scc.kit.edu/4.0/dns/record/imp"
--data "@import_rr.json"
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf:
curl --config curl.cfg

Einfache Dateneingabe durch eine Einzelbefehls-Transaktion mit nicht-leerer Antwort (nd.device.imp)

  • Ziel: Importieren der Device-Daten (L-Ports, IP-Interfaces, nicht-statische Objektattribute)
  • Vorbereitung: Bereitstellen des Request Body als JSON-Dokument (z.B. als Eingabedatei import_dev.json).
{
  "new": {
    "fqdn": "mydevice.kit.test",
    "nc": "cs",
    "acg": "rz-netze-mgmt",
    "type": "z",
    "description": "more details about mydevice",
    "import_data": {
      "nd.l_port_imp": [ {"name": "1", "tag_list": ["static"]}, {"name": "2"} ],
      "nd.ip_intf_imp": [ {"ip_addr": "abcd::1", "l_port_name": "1"}, {"ip_addr": "192.168.1.1", "l_port_name": "1"}],
      "nd.device_attribute_imp": [ {"key_word": "os_name", "value": "OS name/version of mydevice"}, {"key_word": "gen_single_ii_port_name", "value": "1"} ]
    }
  }
}
  • Die in obiger Datei nicht enthaltenen, aber erforderlichen Daten für System, Objekttyp und Funktion werden in der URI-Adresse übergeben
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--url "https://api.netdb.scc.kit.edu/4.0/nd/device/imp"
--data "@import_dev.json"
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf:
curl --config curl.cfg

Einfache Dateneingabe durch eine Einzelbefehls-Transaktion mit leerer Antwort (dns.record.delete)

  • Ziel: Inhalt: Löschen eines DNS-A-Records eines RR-Sets (Satz von potenziell mehreren Records)
  • Vorbereitung: Bereitstellen des Request Body als JSON-Dokument (z.B. als Eingabedatei delete_rr.json).
{
  "old": {
    "fqdn": "myhost.kit.test",
    "type": "A",
    "data": "192.168.1.1"
  }
}
  • Die in obiger Datei nicht enthaltenen, aber erforderlichen Daten für System, Objekttyp und Funktion werden in der URI-Adresse übergeben
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--url "https://api.netdb.scc.kit.edu/4.0/dns/record/delete"
--data "@delete_rr.json"
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf:
curl --config curl.cfg

Komplexe Transaktion mit mehreren Dateneingaben und -Ausgaben und expliziter Statement-Indizierung

  • Ziel: Die folgenden 4 Statements (mit Indexangabe) bewirken:

    • "ls_create" Erzeugen eines neuen Lease-Datensatzes
    • "og_create" Erzeugen einer neuen Optionsgruppe (OG)
    • "og2ls_create" Erzeugen einer neuen Lease-Optionsgruppen-Zuordnung zur Lease aus dem Stmt-Index “ls_create” und zur OG aus dem Stmt-Index “og_create”
    • "addr_list" Ausgabe des via Stmt-Index “ls_create” zugeordneten IP-Adress-Datensatzes
    • "subnet_list" Ausgabe des Subnetzes zur IP-Adresse via Stmt-Index “addr_list” mit JOIN

  • Vorbereitung:

    • Auswahl der Indexnamen für alle Statements
    • Einsetzen der Indexnamen in die referenzierenden JOIN-Anweisungen und Bezugsparameter
    • Ermitteln der Parameter-Namen unter Abfrage des Funktionsindexes für die relevanten Objekttypen lease, og, og2lease des Systems dhcpv4
    • Bereitstellen des Request Body als JSON-Dokument (z.B. als Eingabedatei mod_dhcp.json)
[
  {"idx": "ls_create", "name": "dhcpv4.lease.create", "new": {"ip_subnet_cidr":"192.168.1.0/24", "ip_addr_value":"192.168.1.1", "mac_addr":"00:11:22:aa:bb:cc", "is_static_addr":true }},
  {"idx": "og_create", "name": "dhcpv4.og.create", "new": {"name": "wapi-test-optgroup", "ip_subnet_cidr": "192.168.1.0/24"} },
  {
    "idx": "og2ls_create",
    "name": "dhcpv4.og2lease.create",
    "new_ref_params": [
      { "idx": "ls_create", "params": {"lease_gfk": "gpk" } },
      { "idx": "og_create", "params": {"og_gfk": "gpk"}, "join_type":"inner" }
    ],
    "new": { "priority": 15 }
  },
  {"idx": "addr_list", "name": "dns.ip_addr.list", "inner_join_ref": {"ls_create": "default"} },
  {"idx": "subnet_list", "name": "nd.ip_subnet.list", "inner_join_ref": {"addr_list": "default"}}
]
  • generischer Transaktionsaufruf im Test-Modus (es werden keine Daten permanent gespeichert, aber die Ausgabedaten werden trotzdem erzeugt):
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--url "https://api.netdb.scc.kit.edu/4.0/wapi/transaction/execute?dry_mode=true"
--data "@mod_dhcp.json"
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf:
curl --config curl.cfg

Bedingte Statements mit der WHEN-Anweisung

FQDN des Typs ‘domain’ eintragen, falls noch nicht vorhanden

  • Ziel: Sicherstellen, dass ein bestimmter FQDN mit vorgegebenem Typ existiert. Die Transaktion ist beliebig oft wiederholbar, ohne dass wg. FQDN-Duplikaten eine Exception entsteht.
  • Vorbereitung: Bereitstellen des Request Body als JSON-Dokument (z.B. als Eingabedatei create_fqdn_if_not_exists.json).
  • Das erste Statement dient der Abfrage ‘existiert der FQDN myhost.scc.kit.test?’
  • Das zweite und dritte Statement wird in Abhängigkeit der Antwort des ersten Statements ausgeführt:
    • FQDN anlegen, wenn nicht vorhanden
    • FQDN-Typ ändern, wenn FQDN vorhanden, aber Typ nicht ‘domain’
[
  {"idx": "list_fqdn", "name": "dns.fqdn.list", "old": {"value_list": ["myhost.scc.kit.test"] }},
  {"idx": "crt_fqdn", "name": "dns.fqdn.create", "new": {"value": "myhost.scc.kit.test", "type": "domain"}, "when": {"returns_no_data": ["list_fqdn"]}},
  {
    "idx": "upd_fqdn",
    "name": "dns.fqdn.update",
    "old": {"value": "myhost.scc.kit.test"},
    "new": {"type": "domain"},
    "when": {
      "and": [
        {"returns_data": ["list_fqdn"]},
        {"compare": [ "ne", {"returned_param_value": [ "list_fqdn", "type" ] }, "domain" ]}
      ]
    }
  }
]
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--url "https://api.netdb.scc.kit.edu/4.0/wapi/transaction/execute"
--data "@create_fqdn_if_not_exists.json"
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf:
curl --config curl.cfg

RR-Set importieren, falls nicht exakt übereinstimmend

  • Ziel: Sicherstellen, dass zu einem bestimmten FQDN ein bestimmtes RR-Set existiert. Der Import würde zwar keine Exception werfen, wenn das RR-Set schon existiert, wird aber aus Performance-Gründen nur dann ausgeführt, wenn tatsächlich erforderlich.
  • Vorbereitung: Bereitstellen des Request Body als JSON-Dokument (z.B. als Eingabedatei create_rr_if_not_exists.json).
  • Das erste Statement dient der Abfrage ‘welches MX-RR-Set hat der FQDN scc.kit.test?’. Durch die Sortierung ist eine eindeutige Reihenfolge garantiert.
  • Das zweite Statement wird ausgeführt, wenn das erste Statement nicht genau das verlangte RR-Set zurückgibt. Der Array-Vergleich zielt auf Position und Inhalt der Array-Elemente (trailing dot im statischen Vergleichsarray nicht vergessen!).
[
  {"idx": "list_rr", "name": "dns.record.list", "old": {"fqdn_list": ["scc.kit.test"], "type": "MX", "sorting_params_list":["data"] }},
  {
    "idx": "imp_rr",
    "name": "dns.record.imp",
    "new": {
      "fqdn": "scc.kit.test",
      "strict_mode": false,
      "import_data": { "dns.record_imp": [ { "type": "MX", "data_list": ["10 scc-mailin-cn-01.scc.kit.edu.", "10 scc-mailin-cs-01.scc.kit.edu."] } ] }
    },
    "when": {
      "compare": [
        "ne",
        ["10 scc-mailin-cn-01.scc.kit.edu.", "10 scc-mailin-cs-01.scc.kit.edu."],
        {"returned_param_value_list": [ "list_rr", "data" ] }
      ]
    }
  }
]
  • Inhalt der curl-Konfigurationsdatei curl.cfg:
--url "https://api.netdb.scc.kit.edu/4.0/wapi/transaction/execute"
--data "@create_rr_if_not_exists.json"
--header "Content-Type: application/json"
--header "Authorization: Bearer ***AUTH-TOKEN-TEXT***"
  • Aufruf:
curl --config curl.cfg

Wiederholte Statements mit der RefParams-Anweisung

Löschen einer Subdomain (einschließlich)

  • Ziel: alle DNS-Einträge rekursiv unterhalb eines vorgegebenen FQDNs löschen, einschließlich des vorgegebenen FQDNs selbst. Es werden auch RRs gelöscht, die auf einen zu löschenden FQDN zeigen (RR-Target liegt in der zu löschenden Subdomain)
  • Das erste Statement dient der Festlegung des Startwertes (vorgegebener FQDN)
  • Das zweite Statement gibt alle darunterliegenden FQDNs aus, beginnend mit der untersten Ebene. Die Reihenfolge der Ebenen ist für die fehlerfreie Löschung erforderlich.
  • Das dritte Statement löscht alle FQDNs und deren RRs, die im zweiten Statement ausgegeben wurden (gleiche Reihenfolge).
[
  {"idx": "list_fqdn", "name": "dns.fqdn.list", "old": {"value_list": ["scc.kit.test"] }},
  {
    "idx": "list_subtree",
    "name": "dns.fqdn.list",
    "old": {
      "filter_params_dict": {"show": true, "attrs_list": ["value","tree_level","type","zone"]},
      "sorting_params_list":["tree_level desc", "value"]
    },
    "inner_join_ref": {"list_fqdn": "api_func_dns_fqdn_is_superset_of_root_node_set" }
  },
  {
    "idx": "del_fqdn",
    "name": "dns.fqdn.delete",
    "old": {"force_del_ref_records": true, "try_del_parent": false},
    "old_ref_idx": "list_subtree"
  }
]

Löschen einer Subdomain (ausschließlich)

  • Ziel: alle DNS-Einträge rekursiv unterhalb eines vorgegebenen FQDNs löschen, ausschließlich des vorgegebenen FQDNs selbst. Es werden auch RRs gelöscht, die auf einen zu löschenden FQDN zeigen (RR-Target liegt in der zu löschenden Subdomain)
  • Statement list_fqdn dient der Festlegung des Startwertes (vorgegebener FQDN)
  • Statement list_subtree gibt alle darunterliegenden FQDNs aus, beginnend mit der untersten Ebene. Die Reihenfolge der Ebenen ist für die fehlerfreie Löschung erforderlich.
  • Statement del_fqdn löscht alle FQDNs und deren RRs,
    • die im Statement list_subtree ausgegeben wurden
    • abzüglich der FQDNs des Statements list_fqdn (genau einer; bedient obiges Ausschlußkriterium)
[
  {"idx": "list_fqdn", "name": "dns.fqdn.list", "old": {"value_list": ["scc.kit.test"] }},
  {
    "idx": "list_subtree",
    "name": "dns.fqdn.list",
    "old": {
      "filter_params_dict": {"show": true, "attrs_list": ["value","tree_level","type","zone"]},
      "sorting_params_list":["tree_level desc", "value"]
    },
    "inner_join_ref": {"list_fqdn": "api_func_dns_fqdn_is_superset_of_root_node_set" }
  },
  {
    "idx": "del_fqdn",
    "name": "dns.fqdn.delete",
    "old": {"force_del_ref_records": true, "try_del_parent": false},
    "old_ref_params": [
      {"idx": "list_subtree"},
      {"idx": "list_fqdn", "params": {}, "join_type": "left_anti", "join_on": "val"}
    ]
  }
]

Vorlage zum Testen mit dem generischen Objekttyp unter Verwendung der RefParams-Anweisung

[
  {
    "idx": "defineData1", "name": "tmp.generic_object.list",
    "ref_params_join_on_val_attrs_tuple": ["name"],
    "old": {
      "_dict_list": [
        { "pk": 110, "name": "a", "descr": "1a" },
        { "pk": 120, "name": "b", "descr": null },
        { "pk": 130, "name": "c", "descr": "1c" }
      ]
    }
  },
  {
    "idx": "defineData2", "name": "tmp.generic_object.list",
    "ref_params_join_on_val_attrs_tuple": ["name"],
    "old": {
      "_dict_list": [
        { "pk": 210, "name": "b", "remark": null },
        { "pk": 220, "name": "c", "remark": "remark_e" },
        { "pk": 230, "name": "d", "remark": "remark_f" }
      ]
    }
  },
  {
    "idx": "defineData3", "name": "tmp.generic_object.list",
    "ref_params_join_on_val_attrs_tuple": ["name"],
    "old": {
      "_dict_list": [
        { "pk": 310, "name": "d", "descr": null, "remark": "3d" },
        { "pk": 320, "name": "e", "descr": "3e", "remark": null },
        { "pk": 330, "name": "f", "descr": "3f", "remark": "3f" }
      ]
    }
  },
  {
    "title": "Concat results from several list queries that cannot be expressed as one.",
    "description": "This example demonstrates parameter mapping results for SQL NULL, JSON NULL and NOT NULL values, including default value in 'new'.",
    "description": "Join type 'full_outer' or 'full_anti' must be used together with position based join and 'join_offset_by_idx_list'.",
    "description": "Both join types produce equivalent results; comparable to a logical disjunction (OR).",
    "idx": "qryData1", "name": "tmp.generic_object.create",
    "new_ref_params": [
      { "idx": "defineData1", "params": {"id": "pk", "name": "name" } },
      { "idx": "defineData2", "params": {"id": "pk", "name": "name", "descr": "remark" }, "join_type": "full_outer", "join_offset_by_idx_list": ["defineData1"] },
      { "idx": "defineData3", "params": {"id": "pk", "name": "name", "descr": "descr" }, "join_type": "full_outer", "join_offset_by_idx_list": ["defineData1", "defineData2"] }
    ]
  },
  {
    "title": "Filter different results from several list queries.",
    "description": "Show only result sets that exist exclusive in either one of the ref params results, comparable to a logical exclusive disjunction (XOR).",
    "idx": "qryData2", "name": "tmp.generic_object.create",
    "ref_params_join_on_val_attrs_tuple": ["name"],
    "new_ref_params": [
      { "idx": "defineData1" },
      { "idx": "defineData2",  "join_type": "full_anti", "join_on": "val" }
    ]
  },
  {
    "title": "Filter equal results from several list queries.",
    "description": "Show only result sets that exist in both of the ref params results, comparable to a logical conjunction (AND).",
    "idx": "qryData3", "name": "tmp.generic_object.create",
    "ref_params_join_on_val_attrs_tuple": ["name"],
    "new_ref_params": [
      { "idx": "defineData1" },
      { "idx": "qryData2",  "join_type": "inner", "join_on": "val" }
    ]
  },
  {
    "title": "Update example",
    "description": "In an update the maximum number of the result sets of either old_ref_params or new_ref_params is being used.",
    "description": "An equal number of result sets is being recommended, hence missing parameter values (from missing result sets) are treated as NULL.",
    "description": "The old referenced statement returns 9 result sets, while the new referenced statement returns only 2.",
    "description": "The update function receives the first 2 result sets with complete old/new pairs,",
    "description": "and the remaining 7 result sets having only old values.",
    "description": "The parameter values in the 7 new result sets do not exist and would be in this case NULL respective the default value, if defined.".
    "idx": "qryData4", "name": "tmp.generic_object.update",
    "old_ref_params": [ { "idx": "qryData1", "params": {"id": "id", "name": "name", "descr": "descr" } } ], 
    "new_ref_params": [ { "idx": "qryData2", "params": {"id": "pk", "name": "name", "descr": "descr" } } ]
  },
  { 
    "idx": "qryData5", "name": "tmp.generic_object.list",
    "old_ref_params": [ { "idx": "qryData1", "params": {"id": "id", "name": "name", "descr": "descr" } } ]
  }
]