第3章 API 構文
API リクエストと JSON レスポンスの基本的な構文を確認できます。
Satellite 6 API のバージョン 1 と 2 が利用可能ですが、Red Hat はバージョン 2 のみをサポートしています。
3.1. API リクエストの構成
Satellite に含まれている API リファレンスは、HTTP メソッドの後に API ルートまたはパスを記載します。
HTTP_METHOD API_ROUTE
API を使用するには、curl コマンド構文と当リファレンスドキュメントの API ルートを使用して、コマンドを構築します。
$ curl --request HTTP_METHOD \ 1 --insecure \ 2 --user My_User_Name:My_Password \ 3 --data @input_file.json \ 4 --header "Accept:application/json" \ 5 --header "Content-Type:application/json" \ 6 --output output_file 7 API_ROUTE \ 8 | python3 -m json.tool 9
- 1
- API 呼び出しに
curlを使用するには、HTTP 動詞に--requestオプションを指定します。(例:--request POST)。 - 2
--insecureオプションを追加して、SSL ピア証明書の検証確認をスキップします。Red Hat では、SSL 認証を設定し、セキュリティーで保護された呼び出しを使用することを推奨します。詳細は、「SSL 認証の概要」 を参照してください。- 3
--userオプションを使用して Satellite ユーザーの認証情報を指定します。- 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モジュールに出力をリダイレクトして、出力の可読性を向上します。
3.1.1. HTTP メソッド (GET) の使用
HTTP メソッド (GET) を使用して、既存のエントリーまたはリソースに関するデータを API から取得します。
例
この例では、Satellite ホストの数を要求します。
要求例:
$ curl --request GET --user My_User_Name:My_Password \ https://satellite.example.com/api/hosts | python3 -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 応答形式」 を参照してください。
3.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 My_User_Name:My_Password \ --data @activation-key.json \ https://satellite.example.com/katello/api/activation_keys \ | python3 -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 で、Content > Lifecycle > Activation Keys に移動して、アクティベーションキーを表示します。
3.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 --request PUT \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --user My_User_Name:My_Password \ --data @activation-key.json \ https://satellite.example.com/katello/api/activation_keys/2 \ | python3 -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 で、Content > Lifecycle > Activation Keys に移動して変更を確認します。
3.1.4. HTTP メソッド (DELETE) の使用
リソースを削除するには、削除するリソース ID を含む API ルートと DELETE メソッドを使用します。
例
この例では、ID が 2 の TestKey アクティベーションキーを削除します。
要求例:
$ curl \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --request DELETE \ --user My_User_Name:My_Password \ https://satellite.example.com/katello/api/activation_keys/2 \ | python3 -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
