API (v2) オブジェクト管理

コマンド	対応状況	備考
GET	✅	任意の NameSpace を指定可能
SET	✅	任意の NameSpace を指定可能
CREATE	✅	key/value 引数に対応
DESTROY	✅	基本的なオブジェクト削除
GETOBJECT	✅	FIND + GET の一体型
GETALL	✅	オブジェクト一括取得

GET:

GET リクエストは CODB からデータを取得するために使います。対象の数値 Object ID (OID) を指定する必要があります。OID のみを指定した場合は、そのオブジェクト本体のデータが返されます。OID に加えて NameSpace を指定した場合は、そのオブジェクトの該当 NameSpace のデータが返されます。

Object ID は FIND または FINDX コマンドで調べられます。NameSpace 名は NAMES コマンドで確認できます。

ローカルリクエスト（NameSpace なし）:

curl -k -s \
  -X POST https://127.0.0.1:9092/v2/cce \
  -d '
        {
            "cmd": "GET 6",
            "user": "admin",
            "sessionid": "SESSION-ID"
        }
      ' \
  | jq

ローカルリクエスト（NameSpace あり）:

curl -k -s \
  -X POST https://127.0.0.1:9092/v2/cce \
  -d '
        {
            "cmd": "GET 6. Email",
            "user": "admin",
            "sessionid": "SESSION-ID"
        }
      ' \
  | jq

リモートリクエスト（NameSpace なし）:

curl -k -s \
  -X POST https://127.0.0.1:9092/v2/cce \
  -H "Content-Type: application/json" \
  -H "X-Client-Secret: CLIENT-SECRET" \
  -d '
        {
            "cmd": "GET 6",
            "token": "TOKEN"
        }
      ' \
  | jq

リモートリクエスト（NameSpace あり）:

curl -k -s \
  -X POST https://127.0.0.1:9092/v2/cce \
  -H "Content-Type: application/json" \
  -H "X-Client-Secret: CLIENT-SECRET" \
  -d '
        {
            "cmd": "GET 6. Email",
            "token": "TOKEN"
        }
      ' \
  | jq

レスポンス（成功）:

{
    "status": 201,
    "message": "GOODBYE",
    "data": {
        "DATA": {
            "CLASS": "User",
            "CLASSVER": "1.0",
            "NAMESPACE": "",
            "OID": "6",
            "capLevels": "",
            "capabilities": "",
            "crypt_password": "XXXX",
            "desc_readonly": "0",
            "description": "",
            "emailDisabled": "0",
            "enabled": "1",
            "ftpDisabled": "0",
            "fullName": "Administrator",
            "gui_theme": "elmer",
            "gui_theme_timer": "0",
            "localePreference": "en_US",
            "md5_password": "XXXX",
            "name": "admin",
            "noFileCheck": "0",
            "password": "",
            "shell": "",
            "site": "",
            "sortName": "",
            "stylePreference": "BlueOnyx",
            "systemAdministrator": "1",
            "uiRights": "",
            "ui_enabled": "1",
            "volume": "/home"
        }
    }
}

レスポンス（失敗）:

{
    "status": 401,
    "message": "GOODBYE",
    "data": {
        "errors": [
            {
                "code": 300,
                "message": "UNKNOWN OBJECT 6"
            },
            {
                "code": 401,
                "message": "FAIL"
            }
        ]
    }
}

SET:

SET リクエストは、既存の CODB オブジェクトまたは NameSpace の値を更新するために使います。書き込み対象オブジェクトの OID を知っている必要があります。NameSpace を指定しない場合はオブジェクト本体に対して書き込みます。NameSpace を指定した場合は、その NameSpace に対して SET データが適用されます。

ローカルリクエスト（NameSpace なし）:

curl -k -s \
  -X POST https://127.0.0.1:9092/v2/cce \
  -d '
        {
            "cmd": "SET 6 localePreference = \"en_US\"",
            "user": "admin",
            "sessionid": "SESSION-ID"
        }
      ' \
  | jq

リモートリクエスト（NameSpace あり）:

curl -k -s \
  -X POST https://API-IP:9092/v2/cce \
  -H "Content-Type: application/json" \
  -H "X-Client-Secret: CLIENT-SECRET" \
  -d '
        {
            "cmd": "SET 6. Email \"forwardEmail\" = \"0\"",
            "token": "TOKEN"
        }
      ' \
  | jq

レスポンス（成功）:

{
    "status": 201,
    "message": "GOODBYE",
    "data": {
        "DATA": []
    }
}

レスポンス（失敗）:

{
 "status": 401,
 "message": "GOODBYE",
 "data": {
 "DATA": {},
 "errors": [
 {
 "code": 302,
 "message": "BAD DATA 6 forwardXmail "[[base-cce.unknownAttr]]""
 },
 {
 "code": 401,
 "message": "FAIL"
 }
 ]
 }
}

CREATE:

CREATE は CODB オブジェクトを新規作成するための機能です。どのクラスのオブジェクトを作成するかを指定する必要があります。そのクラスに NameSpace がある場合は、既定値付きで自動的に追加されます。CREATE 時には、新規オブジェクトに設定する key/value を渡せますし、多くの場合は必須です。すべてを明示的に渡す必要はありませんが、未指定部分には既定値が入ります。ただし一部のオブジェクトでは必須値や一意性、特定ルールへの適合が必要で、それを満たさないと CREATE は失敗します。

以下は localhost API 呼び出しとリモート API 呼び出しで Vsite を作成する例です。

CREATE に成功すると、新規作成されたオブジェクトの OID が返されます。失敗時には、原因調査に役立つ警告やエラーが返ることがあります。典型的な失敗原因は、必須値の不足や、条件違反によりハンドラがトランザクションを拒否した場合です。下のリモート利用例では、192.168.151.218 という IP アドレスが対象 BlueOnyx 上で使用許可されていないことが失敗理由です。

ローカルリクエスト:

curl -k -s \
  -X POST https://127.0.0.1:9092/v2/cce \
  -H "Content-Type: application/json" \
  -d '
        {
            "cmd": "CREATE",
            "class": "Vsite",
            "user": "admin",
            "sessionid": "REPLACE_WITH_SESSION_ID",
            "data": {
                "mailAliases": "",
                "fqdn": "t2.smd.net",
                "mailCatchAll": "",
                "hostname": "t2",
                "ipaddr": "192.168.151.218",
                "ipaddrIPv6": "",
                "userPrefixEnabled": "0",
                "maxusers": "25",
                "volume": "/home",
                "dns_auto": "0",
                "userPrefixField": "",
                "site_preview": "0",
                "createdUser": "admin",
                "emailDisabled": "0",
                "domain": "smd.net",
                "prefix": "",
                "webAliases": "",
                "webAliasRedirects": "1"
            }
        }
      ' \
  | jq

リモートリクエスト:

curl -k -s \
  -X POST https://API-IP:9092/v2/cce \
  -H "Content-Type: application/json" \
  -H "X-Client-Secret: CLIENT-SECRET" \
  -H "Content-Type: application/json" \
  -d '
        {
            "cmd": "CREATE",
            "class": "Vsite",
            "user": "admin",
            "token": "REPLACE_WITH_TOKEN",
            "data": {
                "mailAliases": "",
                "fqdn": "t2.smd.net",
                "mailCatchAll": "",
                "hostname": "t2",
                "ipaddr": "192.168.151.218",
                "ipaddrIPv6": "",
                "userPrefixEnabled": "0",
                "maxusers": "25",
                "volume": "/home",
                "dns_auto": "0",
                "userPrefixField": "",
                "site_preview": "0",
                "createdUser": "admin",
                "emailDisabled": "0",
                "domain": "smd.net",
                "prefix": "",
                "webAliases": "",
                "webAliasRedirects": "1"
            }
        }
      '

レスポンス（成功）:

{
    "status": 201,
    "message": "GOODBYE",
    "data": {
        "DATA": [],
        "oidlist": [
            "63"
        ]
    }
}

レスポンス（失敗）:

{
 "status": 401,
 "message": "GOODBYE",
 "data": {
 "DATA": {},
 "errors": [
 {
 "code": 305,
 "message": "WARN "[[base-network.ip_restricted,ipaddr="192.168.151.218"]]""
 },
 {
 "code": 401,
 "message": "FAIL"
 }
 ],
 "oidlist": [
 "63"
 ]
 }
}

DESTROY:

DESTROY は Object ID (OID) を受け取り、対象オブジェクトを CODB から削除しようとします。関連するすべての NameSpace も削除されます。ACL、OID の不存在、依存関係、または削除中にハンドラが返したエラーなどにより失敗する場合があります。

ローカルリクエスト:

curl -k -s \
  -X POST https://127.0.0.1:9092/v2/cce \
  -H "Content-Type: application/json" \
  -d '{ "cmd": "DESTROY 63", "user": "admin", "sessionid": "REPLACE_WITH_SESSION_ID", }' \
  | jq

リモートリクエスト:

curl -k -s \
  -X POST https://API-IP:9092/v2/cce \
  -H "Content-Type: application/json" \
  -H "X-Client-Secret: CLIENT-SECRET" \
  -d '{ "cmd": "DESTROY 63", "user": "admin", "token": "REPLACE_WITH_TOKEN", }' \
  | jq

レスポンス（成功）:

{
    "status": 201,
    "message": "GOODBYE",
    "data": {
        "DATA": []
    }
}

レスポンス（失敗）:

{
    "status": 401,
    "message": "GOODBYE",
    "data": {
        "DATA": [],
        "errors": [
            {
                "code": 300,
                "message": "UNKNOWN OBJECT 63"
            },
            {
                "code": 401,
                "message": "FAIL"
            }
        ]
    }
}

GETOBJECT:

GETOBJECT は FIND と GET を組み合わせたコマンドで、検索条件に一致するオブジェクトを返します。

ローカルリクエスト:

curl -k -s \
  -X POST https://127.0.0.1:9092/v2/cce \
  -d '
        {
            "cmd": "GETOBJECT",
            "class": "Vsite",
            "args": {
                "name": "site1"
            },
            "namespace": "",
            "user": "admin",
            "sessionid": "SESSION-ID"
        }
      ' \
  | jq

リモートリクエスト:

curl -sk \
  -X POST https://API-IP:9092/v2/cce \
  -H "Content-Type: application/json" \
  -H "X-Client-Secret: CLIENT-SECRET" \
  -d '
        {
            "cmd": "GETOBJECT",
            "class": "Vsite",
            "args": {
                "name": "site1"
            },
            "token": "TOKEN"
        }
      ' \
  | jq

レスポンス（成功）:

{
    "status": 201,
    "message": "OK",
    "data": {
        "DATA": {
            "basedir": "/home/.sites/site1",
            "class": "Vsite",
            "classver": "1.0",
            "createduser": "admin",
            "dns_auto": "1",
            "domain": "smd.net",
            "emaildisabled": "0",
            "force_update": "1747164973",
            "fqdn": "t1.smd.net",
            "hostname": "t1",
            "ipaddr": "208.77.151.218",
            "ipaddripv6": "",
            "mailaliases": "",
            "mailcatchall": "",
            "maxusers": "25",
            "name": "site1",
            "namespace": "",
            "oid": "34",
            "prefix": "",
            "site_preview": "0",
            "siteadmincaps": "",
            "suspend": "0",
            "userprefixenabled": "0",
            "userprefixfield": "",
            "userwebsdisabled": "0",
            "volume": "/home",
            "webaliases": "",
            "webaliasredirects": "1"
        }
    }
}

レスポンス（失敗）:

{
    "status": 404,
    "message": "Object not found"
}

GETALL:

GETALL は FIND と GET を組み合わせたコマンドで、検索条件に一致する 1 個以上のオブジェクトと、そのすべての NameSpace を返します。OID を既に知っている場合は OID 指定で、そうでなければ引数指定で検索できます。

ローカルリクエスト:

curl -k -s \
  -X POST https://127.0.0.1:9092/v2/cce \
  -d '
        {
            "cmd": "GETALL",
            "oids": [
                "56",
                "58"
            ],
            "args": {
                "name": "site1"
            },
            "user": "admin",
            "sessionid": "SESSION-ID"
        }
      ' \
  | jq

リモートリクエスト:

curl -k -s \
  -X POST https://API-IP:9092/v2/cce \
  -H "Content-Type: application/json" \
  -H "X-Client-Secret: CLIENT-SECRET" \
  -d '
        {
            "cmd": "GETALL",
            "oids": [
                "56",
                "58"
            ],
            "args": {
                "name": "site1"
            },
            "token": "TOKEN"
        }
      ' \
  | jq

レスポンス（成功）:

{
 "status": 201,
 "message": "OK",
 "data": {
 "objects": {
 "56": { // <--- First OID with all NameSpaces
 "Disk": {
 [...]
 },
 "Email": {
 [...]
 },
 "ImapSync": {
 [...]
 },
 "OBJECT": {
 [...]
 },
 "Radicale": {
 [...]
 },
 "RootAccess": {
 [...]
 },
 "SSH": {
 [...]
 },
 "Shell": {
 [...]
 },
 "Sites": {
 [...]
 },
 [...]
 },
 "58": { // <--- Second OID with all NameSpaces
 "Disk": {
 [...]
 },
 "Email": {
 [...]
 },
 [...]
 "OBJECT": {
 [...]
 },
 "Radicale": {
 [...]
 },
 "RootAccess": {
 [...]
 },
 "SSH": {
 [...]
 },
 "Shell": {
 [...]
 },
 "Sites": {
 [...]
 },
 "subdomains": {
 [...]
 }
 }
 }
 }
}

レスポンス（失敗）:

{
    "status": 201,
    "message": "GOODBYE",
    "data": {
        "errors": [
            {
                "code": 401,
                "message": "FAIL"
            }
        ],
        "oid": "-1"
    }
}