第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" \ 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 truncatedAPI からの応答により、結果数が合計 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" \ --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" \ --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" \ --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]
