第2章 API リファレンス
完全な API リファレンスは
https://satellite6.example.com/apidoc/v2.html (satellite6.example.com は Satellite サーバーのホスト名に置き換えてください) の Satellite サーバーからご利用いただけます。Satellite 6 API のバージョン 1 と 2 が提供されていますが、Red Hat がサポートしているのはバージョン 2 のみである点に注意してください。
2.1. API 構文の理解
同梱の API リファレンスでは、
HTTP_VERB API_ROUTEなどのように、HTTP の動詞の後に API ルートまたはパスの形式となっています。API が使用する HTTP の動詞は、GET、POST、PUT、DELETE です。例については、
http://satellite6.example.com/apidoc/v2/hosts.html の API リファレンスドキュメントの HOST セクションを参照してください。API 構文および curl コマンドに精通している場合にはこの章は飛ばしてください。
API を利用するには、参照ドキュメントからの API ルートと、コマンドのドキュメントからのコマンド構文を使用してコマンドを構築します。たとえば
curl の man ページでは curl [options] [URL...]などの基本構文が紹介されています。このガイドで使用するオプションには
-X, --request command などが含まれます。command は HTTP の動詞に置き換えてください。
HTTP 動詞 (GET) の使用
HTTP 動詞の GET は、既存のエントリーまたはリソースに関して API からデータを取得するのに使用します。
GET /api/hosts など、API HOST セクションからの例と curl 構文を組み合わせると curl -X GET https://satellite6.example.com/api/hostsといったコマンドになります。Satellite は、API への接続には HTTPS のみをサポートし、一定の形式の認証が必要です。
使用可能な例として、最低でも
-u オプションで名前を、-k オプションで SSL のピア証明書検証を省略する必要があります。
$ curl -X GET -k -u sat_username https://satellite6.example.com/api/hosts
Enter host password for user 'sat_username':
{
"total": 2,
"subtotal": 2,
"page": 1,
"per_page": 20,
"search": null,
"sort": {
"by": null,
"order": null
},
"results":
出力省略
API からの上記の応答により合計の結果数が 2 つで、以下のような 2 つの結果が返されたこと、またこれは結果の 1 ページ目で、ページごとの最大結果数は 20 に設定されていることが分かります。これについては「JSON 応答形式の理解」でさらに詳しく説明しています。
API リファレンスの例には、
:parameter などのように、コロンが先頭にきてその後に用語が含まれるというものがあります。以下に例を示します。GET /api/hosts/:idこれらは API ルートパラメーターで、適切な値に置き換える必要があります。ルートパラメーターは、コロンで始まり
id で終わります。
注記
Satellite 6 では、API のバージョン 2 がデフォルトであるため、API 呼び出しの URL に
v2 を使用する必要はありません。
HTTP 動詞 (POST) の使用
HTTP 動詞の POST は、API にデータを提出して、新規エントリーまたはリソースを作成する際に使用します。データは、JSON 形式を使用する必要があり、
-d, --data オプションの後に、{} カッコで閉じた JSON 形式の引用データを使用してデータをインラインに含めることができます。または、引用なしの JSON 形式のデータはファイルに含めることができ、curl コマンドの @ オプションを使用して指定することができます (例: -d @file.json)。
JSON 形式のデータに外部ファイルを使用する利点として、引用やエスケープの問題が減り、構文チェッカーの付いた任意のエディターを使用してエラーを特定、回避することができ、JSON データの妥当性を確認して再フォーマットする外部ツールを使用できる点が挙げられます。たとえば、yajl パッケージには
json_verify ツールと json_reformat ツールが含まれています。
json_verify ツールを使用すると、以下のように JSON ファイルの妥当性を確認することができます。
$ json_verify < test_file.json
API 呼び出しで返された非構造化 JSON データは、Python モジュールで
json.tool: curl API_call | python -m json.toolのようにパイプすることができます。または、:
curl API_call | json_reformatのように、
json_reformat ツールを使用してください。出力形式は「JSON 応答形式の理解」で説明しています。
API リファレンスには、Activation keys セクションの
POST /katello/api/activation_keysが含まれます。
これは、
POST /katello/api/activation_keys コマンドの形式の一例です。
curl -X POST -k -u sat_username:sat_password \ -d @file_of_json-formatted_data \ https://satellite6.example.com/katello/api/activation_keys
HTTP 動詞の POST がどのように機能するかを確認するには、以下のような内容が含まれる
activation-key.json などのテストファイルを作成します。
{"organization_id":1, "name":"TestKey", "description":"Just for testing"}
以下の例では、先程作成したファイルのデータを適用して、新規アクティベーションキーを作成します。
$Ｗeb UI でこのエントリーを表示するには、curl -H "Accept:application/json,version=2" \-H "Content-Type:application/json" -X POST \-u sat_username:sat_password -k \-d @activation-key.json \https://satellite6.example.com/katello/api/activation_keys | json_reformat{ "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 } }
HTTP 動詞 (PUT) の使用
HTTP 動詞の PUT は、API にデータを送信して既存のエントリーまたはリソースを更新するのに使用します。POST API 呼び出しと同様に、データは JSON 形式を使用する必要があり、
-d, --data オプションの後に、{} カッコで閉じた JSON 形式の引用データを使用してデータをインラインに含めることができます。または、引用なしの JSON 形式のデータはファイルに含めることができ、curl コマンドの @ オプションを使用して指定することができます (例: -d @file.json)。
既存の値を変更するか、既存のリソースに値を追加するには、HTTP 動詞の PUT を使用します。API リファレンスには、
PUT /katello/api/activation_keys/:idのように、アクティベーションキーを更新するエントリーがあります。
既存のアクティベーションキーを更新するには、以下の形式のコマンドを使用します。
curl -X PUT -k -u sat_username:sat_password \ -d @file_of_json-formatted_data \ https://satellite6.example.com/katello/api/activation_keys/:id:id は、更新するアクティベーションキーの ID に置き換えます。同じ値で PUT コマンドを複数回使用しても、エントリーは複数 作成されません。
たとえば、以前の例で作成したテスト用のアクティベーションキーを更新するには、以下のように以前作成したファイルを編集します。
{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }
以下のコマンドを使用して、JSON ファイルに変更を適用します。
$curl -H "Accept:application/json,version=2" \-H "Content-Type:application/json" -X PUT \-u sat_username:sat_password -k \-d @activation-key.json \https://satellite6.example.com/katello/api/activation_keys/2{ "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 } }
HTTP 動詞 (DELETE) の使用
リソースを削除するには、削除するリソース ID を含む API ルートと DELETE 動詞を使用します。
既存のアクティベーションキーを削除するには、以下の形式のコマンドを使用します。
curl -X DELETE -k -u sat_username:sat_password \ https://satellite6.example.com/katello/api/activation_keys/:id:id は削除するアクティベーションキーの ID に置き換えます。以下に例を示します。
$curl -H "Accept:application/json,version=2" \-H "Content-Type:application/json" -X DELETE \-u admin:RedHat1! -k \https://satellite6.example.com/katello/api/activation_keys/2 | json_reformat出力省略 "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"出力省略
API エラーメッセージと API リファレンスの関連付け
API はエラーの表示に RAILs 形式を使用します。
Nested_Resource.Attribute_Nameこれは、API リファレンスで使用する以下の形式に変換されます。
Resource[Nested_Resource_attributes][Attribute_Name_id]
