第2章 API リファレンス
包括的な API リファレンスは、お使いの Satellite Server でご確認いただけます (https://satellite.example.com/apidoc/v2.html
)。Satellite 6 API のバージョン 1 と 2 が利用できますが、Red Hat ではバージョン 2 のみをサポートする点に注意してください。
2.1. API 構文の理解
Satellite に含まれている API リファレンスは、HTTP 動詞の後に API ルートまたはパスを記載します。
HTTP_VERB API_ROUTE
API を使用するには、curl
コマンド構文と当リファレンスドキュメントの API ルートを使用して、コマンドを構築します。
$ curl --request HTTP_VERB \ 1 --insecure \ 2 --user sat_username:sat_password \ 3 --data @file.json \ 4 --header "Accept:application/json,version=2" \ 5 --header "Content-Type:application/json" \ 6 --output file 7 API_ROUTE \ 8 | python -m json.tool 9
- 1
- API 呼び出しに
curl
を使用するには、HTTP 動詞に--request
オプションを指定します (例:--request POST
)。 - 2
--insecure
オプションを追加して、SSL ピア証明書の検証確認をスキップします。- 3
--user
オプションを使用してユーザー認証を指定します。- 4
- 5 6
--data
オプションを指定して JSON データを渡す場合は、--header
オプションを指定して以下のヘッダーを指定する必要があります。詳細情報は、「API 要求への JSON データの指定」を参照してください。- 7
- Satellite Server からコンテンツをダウンロードする場合に、
--output
オプションを使用して、出力ファイルを指定します。 - 8
https://satellite.example.com/katello/api/activation_keys
形式の API ルートを使用します。Satellite 6 では、API バージョン 2 がデフォルトであるため、API 呼び出しの URL にv2
を使用する必要はありません。- 9
- Python
json.tool
モジュールに出力をリダイレクトして、出力の可読性を向上します。
2.1.1. HTTP 動詞 (GET) の使用
HTTP 動詞 (GET) を使用して、既存のエントリーまたはリソースに関するデータを API から取得します。
例
この例では、Satellite ホストの数を要求します。
要求例:
$ curl --request GET --insecure --user sat_username:sat_password \ https://satellite.example.com/api/hosts | python -m json.tool
応答例:
{
"total": 2,
"subtotal": 2,
"page": 1,
"per_page": 20,
"search": null,
"sort": {
"by": null,
"order": null
},
"results":
output truncated
API からの応答により、結果数が合計 2 つ、これらは結果の 1 ページ目に表示され、ページごとの最大結果数は 20 に設定されていることが分かります。詳しい情報は「JSON 応答形式の理解」を参照してください。
2.1.2. HTTP 動詞 (POST) の使用
HTTP 動詞 (POST) を使用して、データを API に送信してエントリーまたはリソースを作成します。JSON 形式でデータを送信する必要があります。詳細情報は、「API 要求への JSON データの指定」を参照してください。
例
この例では、アクティベーションキーを作成します。
以下のコンテンツを含めて、
activation-key.json
などのテストファイルを作成します。{"organization_id":1, "name":"TestKey", "description":"Just for testing"}
activation-key.json
ファイルにデータを適用してアクティベーションキーを作成します。要求例:
$ curl --header "Accept:application/json,version=2" \ --header "Content-Type:application/json" --request POST \ --user sat_username:sat_password --insecure \ --data @activation-key.json \ https://satellite.example.com/katello/api/activation_keys \ | python -m json.tool
応答例:
{ "id": 2, "name": "TestKey", "description": "Just for testing", "unlimited_hosts": true, "auto_attach": true, "content_view_id": null, "environment_id": null, "usage_count": 0, "user_id": 3, "max_hosts": null, "release_version": null, "service_level": null, "content_overrides": [ ], "organization": { "name": "Default Organization", "label": "Default_Organization", "id": 1 }, "created_at": "2017-02-16 12:37:47 UTC", "updated_at": "2017-02-16 12:37:48 UTC", "content_view": null, "environment": null, "products": null, "host_collections": [ ], "permissions": { "view_activation_keys": true, "edit_activation_keys": true, "destroy_activation_keys": true } }
- 新しいアクティベーションキーが存在することを確認します。Satellite Web UI で、コンテンツ > アクティベーションキー に移動して、アクティベーションキーを表示します。
2.1.3. HTTP 動詞 (PUT) の使用
HTTP 動詞 (PUT) を使用して、既存の値を変更するか、既存のリソースに追加します。JSON 形式でデータを送信する必要があります。詳細情報は、「API 要求への JSON データの指定」を参照してください。
例
この例では、1 つ前の例で作成した TestKey
アクティベーションキーを更新します。
先ほど作成した
activation-key.json
ファイルを以下のように編集します。{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }
JSON ファイルの変更を適用します。
要求例:
$ curl --header "Accept:application/json,version=2" \ --header "Content-Type:application/json" --request PUT \ --user sat_username:sat_password --insecure \ --data @activation-key.json \ https://satellite.example.com/katello/api/activation_keys/2 \ | python -m json.tool
応答例:
{ "id": 2, "name": "TestKey", "description": "Just for testing", "unlimited_hosts": false, "auto_attach": true, "content_view_id": null, "environment_id": null, "usage_count": 0, "user_id": 3, "max_hosts": 10, "release_version": null, "service_level": null, "content_overrides": [ ], "organization": { "name": "Default Organization", "label": "Default_Organization", "id": 1 }, "created_at": "2017-02-16 12:37:47 UTC", "updated_at": "2017-02-16 12:46:17 UTC", "content_view": null, "environment": null, "products": null, "host_collections": [ ], "permissions": { "view_activation_keys": true, "edit_activation_keys": true, "destroy_activation_keys": true } }
- Satellite Web UI で、コンテンツ > アクティベーションキー に移動して、変更を確認します。
2.1.4. HTTP 動詞 (DELETE) の使用
リソースを削除するには、削除するリソース ID を含む API ルートと DELETE 動詞を使用します。
例
この例では、ID が 2 の TestKey
アクティベーションキーを削除します。
要求例:
$ curl --header "Accept:application/json,version=2" \ --header "Content-Type:application/json" --request DELETE \ --user sat_username:sat_password --insecure \ https://satellite.example.com/katello/api/activation_keys/2 \ | python -m json.tool
応答例:
output omitted "started_at": "2017-02-16 12:58:17 UTC", "ended_at": "2017-02-16 12:58:18 UTC", "state": "stopped", "result": "success", "progress": 1.0, "input": { "activation_key": { "id": 2, "name": "TestKey" output truncated
2.1.5. API エラーメッセージと API リファレンスの関連付け
API はエラーの表示に RAILS 形式を使用します。
Nested_Resource.Attribute_Name
これは、以下のように、API リファレンスで使用する形式に変換されます。
Resource[Nested_Resource_attributes][Attribute_Name_id]
2.2. JSON 応答形式の理解
API への呼び出しは、JSON 形式の結果を返します。API 呼び出しは、単一オプションの応答または、応答コレクションの結果を返します。
単一オブジェクトの JSON 応答形式
単一オブジェクトで作業するには、単一オブジェクトの JSON 応答を使用します。単一のオブジェクトに対する API 要求では、オブジェクトの一位識別子 :id
が必要です。
これは、ID が 23 の Satellite ドメインに対する単一オブジェクトの形式例です。
要求例:
$ curl --request GET --insecure --user sat_username:sat_password \ https://satellite.example.com/api/domains/23 | python -m json.tool
応答例:
{ "id": 23, "name": "qa.lab.example.com", "fullname": "QA", "dns_id": 10, "created_at": "2013-08-13T09:02:31Z", "updated_at": "2013-08-13T09:02:31Z" }
コレクション用の JSON 応答形式
コレクションは、ホストとドメインなどのオブジェクト一覧です。JSON 応答コレクションの形式は、メタデータのフィールドセクションと結果セクションで構成されます。
以下は、Satellite ドメイン一覧のコレクション要求の形式例です。
要求例:
$ curl --request GET --insecure --user sat_username:sat_password \ https://satellite.example.com/api/domains | python -m json.tool
応答例:
{ "total": 3, "subtotal": 3, "page": 1, "per_page": 20, "search": null, "sort": { "by": null, "order": null }, "results": [ { "id": 23, "name": "qa.lab.example.com", "fullname": "QA", "dns_id": 10, "created_at": "2013-08-13T09:02:31Z", "updated_at": "2013-08-13T09:02:31Z" }, { "id": 25, "name": "sat.lab.example.com", "fullname": "SATLAB", "dns_id": 8, "created_at": "2013-08-13T08:32:48Z", "updated_at": "2013-08-14T07:04:03Z" }, { "id": 32, "name": "hr.lab.example.com", "fullname": "HR", "dns_id": 8, "created_at": "2013-08-16T08:32:48Z", "updated_at": "2013-08-16T07:04:03Z" } ] }
応答メタデータフィールド
API 応答は、以下のメタデータフィールドを使用します。
-
total
: 検索パラメーターなしのオブジェクトの合計数 -
subtotal
: 検索パラメーターを指定して返されたオブジェクト数 (検索がない場合には、累計は合計と同じになります) -
page
: ページ数 -
per_page
: ページごとに返す最大オブジェクト数 -
limit
: コレクションの応答で返すオブジェクトの指定数 -
offset
: コレクションを返す前に省略するオブジェクト数 -
search
:scoped_scoped
構文をもとにした検索文字列 sort
-
by
: API がコレクションをソートするフィールド別に指定します。 -
order
」: ソート順 (ASC は昇順、DESC は降順)
-
-
results
: オブジェクトのコレクション