Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

第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"}
以下の例では、先程作成したファイルのデータを適用して、新規アクティベーションキーを作成します。 
$ 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
    }
}
Ｗeb UI でこのエントリーを表示するには、コンテンツ アクティベーションキー の順に移動します。変更を加えた後は、ページを再読込するのを忘れないでください。

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]
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2026 Red Hatトップに戻る