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

第2章 API リファレンス

包括的な API リファレンスは、お使いの Satellite Server でご確認いただけます( satellite6.example.com は、お使いの Satellite Server のホスト名に置き換えてください)。Satellite 6 API のバージョン 1 と 2 が利用できますが、Red Hat ではバージョン 2 のみをサポートする点に注意してください。

2.1. API 構文の理解
リンクのコピー

ビルトイン API リファレンスは、HTTP 動詞の後に API ルートまたはパスを示します。
HTTP_VERB API_ROUTE
Copy to Clipboard Toggle word wrap
API が使用する HTTP 動詞は、GET、POST、PUT、および DELETE です。一部の例は、http://satellite6.example.com/apidoc/v2/hosts.html の API リファレンスドキュメントの HOSTS セクションを参照してください。API 構文および curl コマンドに慣れている場合は、本セクションをスキップできます。
API を使用するには、リファレンスドキュメントの API ルートと、コマンドのドキュメントからコマンド構文を使用して、コマンドを作成します。たとえば、curl の man ページには、以下の基本的な構文 
curl [options] [URL...]
Copy to Clipboard Toggle word wrap
が表示されます。本ガイドで使用するオプションには -X、--request コマンド が含まれます。ここでの command は HTTP 動詞です。

HTTP 動詞 (GET) の使用

HTTP 動詞の GET は、既存のエントリーまたはリソースに関して API からデータを取得するのに使用します。
GET /api/hosts などの API HOST セクションと curl 構文を組み合わせると、以下のようになります。
curl -X GET https://satellite6.example.com/api/hosts
Copy to Clipboard Toggle word wrap
Satellite は API への接続向けの HTTPS のみをサポートし、一部の認証形式が必要です。
使用可能な例として、少なくとも the -u オプションを指定してユーザー名を追加し、SSL ピア証明書の検証チェックをスキップするには -k オプションを追加する必要があります。 
$ 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":
	output truncated
Copy to Clipboard Toggle word wrap
API からの上記の応答により合計 2 つの結果が返され、以下のような 2 つの結果が返されたこと、これは結果の 1 ページ目で、ページごとの最大結果数は 20 に設定されていることが分かります。これについては、「JSON 応答形式の理解」 で詳細に説明されています。
API リファレンスの例には、:パラメーターの前にコロンが付いた用語が含まれています。たとえば、
GET /api/hosts/:id
Copy to Clipboard Toggle word wrap
これらは API ルートパラメーターであり、適切な値に置き換える必要があります。ルートパラメーターはコロンで始まり、ID が で 終わる。
注記
Satellite 6 では、API のバージョン 2 がデフォルトです。したがって、API 呼び出しの URL に v2 を使用する必要はありません。

HTTP 動詞 (POST) の使用

HTTP 動詞 POST は、データを API に送信して新規エントリーまたはリソースを作成するために使用されます。データは JSON 形式である必要があり、-- d, --data オプションの後に中かっこ {} で囲まれた引用符で囲まれた JSON 形式のデータをイン ラインで含めることができます。引用符で囲まれていない JSON 形式のデータをファイルで囲み、curl コマンドの @ オプションを使用して指定することもできます。たとえば、d @ファイル.json です。
JSON 形式のデータに外部ファイルを使用する利点は、引用やエスケープの問題が少なく、構文チェッカーを備えた好みのエディターを使用して間違いを見つけ、回避でき、JSON データの妥当性を確認して再フォーマットする外部ツールを使用できることです。たとえば、yajl パッケージには、json_verify ツールと json_reformat ツールが含まれています。
json_verify ツールを使用すると、以下のように JSON ファイルの有効性を確認できます。 
$ json_verify < test_file.json
Copy to Clipboard Toggle word wrap
API コールによって返される非構造化 JSON データは、python モジュール json.tool でパイプできます。
curl API_call | python -m json.tool
Copy to Clipboard Toggle word wrap
または、json_reformat ツールを使用してください。
curl API_call | json_reformat
Copy to Clipboard Toggle word wrap
出力形式については、「JSON 応答形式の理解」 で説明されています。
API リファレンスには、アクティベーションキー セクションに以下が含まれます。 
POST /katello/api/activation_keys
Copy to Clipboard Toggle word wrap
これは、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
Copy to Clipboard Toggle word wrap
HTTP 動詞 POST の仕組みを確認するには、以下のように内容を含むテストファイル（例： activation-key.json ）を作成します。 
{"organization_id":1, "name":"TestKey", "description":"Just for testing"}
Copy to Clipboard Toggle word wrap
以下の例では、先程作成したファイルのデータを適用して、新規アクティベーションキーを作成します。 
$ 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
    }
}
Copy to Clipboard Toggle word wrap
Web UI でこのエントリーを表示するには、コンテンツ アクティベーションキー に移動します。変更後は、必ずページを再読み込みしてください。

HTTP 動詞 (PUT) の使用

HTTP 動詞の PUT は、データを API に送信して、既存のエントリーまたはリソースを更新するために使用されます。POST API 呼び出しと同様に、データは JSON 形式である必要があり、d, --data オプションの後に中かっこ {} で囲まれた引用符で囲まれた JSON 形式のデータをイン ラインで含めることができます。引用符で囲まれていない JSON 形式のデータをファイルで囲み、curl コマンドの @ オプションを使用して指定することもできます。たとえば、d @ファイル.json です。
既存の値を変更したり、既存のリソースに追加する場合は、HTTP 動詞(PUT)を使用します。API リファレンスには、アクティベーションキーを更新するための以下のエントリーがあります。 
PUT /katello/api/activation_keys/:id
Copy to Clipboard Toggle word wrap
既存のアクティベーションキーを更新するには、以下の形式のコマンドを使用します。 
curl -X PUT -k -u sat_username:sat_password \
-d @file_of_json-formatted_data \
https://satellite6.example.com/katello/api/activation_keys/:id
Copy to Clipboard Toggle word wrap
:id を、更新するアクティベーションキーの ID に置き換えます。同じ値で PUT コマンドを複数回使用しても、複数のエントリー は作成されません。
たとえば、以前の例で作成したテスト用のアクティベーションキーを更新するには、以下のように以前作成したファイルを編集します。 
{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }
Copy to Clipboard Toggle word wrap
以下のコマンドを使用して、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
    }
}
Copy to Clipboard Toggle word wrap

HTTP 動詞 (DELETE) の使用

リソースを削除するには、削除するリソース ID を含む API ルートと DELETE 動詞を使用します。
既存のアクティベーションキーを削除するには、以下の形式のコマンドを使用します。 
curl -X DELETE -k -u sat_username:sat_password \
https://satellite6.example.com/katello/api/activation_keys/:id
Copy to Clipboard Toggle word wrap
: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
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
Copy to Clipboard Toggle word wrap

API エラーメッセージと API リファレンスの関連付け

API はエラーの表示に RAILS 形式を使用します。 
Nested_Resource.Attribute_Name
Copy to Clipboard Toggle word wrap
これは、以下のように、API リファレンスで使用する形式に変換されます。 
Resource[Nested_Resource_attributes][Attribute_Name_id]
Copy to Clipboard Toggle word wrap

2.2. JSON 応答形式の理解
リンクのコピー

GET を使用した API への呼び出しは、JSON 形式の結果を返します。Python json.tool モジュールを介して出力を渡すと、人間が判読できる形式で出力されます。

コレクション用の JSON 応答形式

コレクションは、ホストとドメインなどのオブジェクトリストです。JSON 応答コレクションの形式は、メタデータのフィールドセクションの後に結果セクションで設定されます。以下は、API ルート GET /api/domains を使用する場合のドメイン一覧のコレクション JSON レスポンスの形式例です。この出力は json.tool でパイプされ、結果セクションを読みやすくしました。 
$ curl -X GET -k -u admin:password https://satellite6.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"
        }
    ]
}
Copy to Clipboard Toggle word wrap
応答のメタデータのフィールドの説明は以下のとおりです。
  • total: 検索パラメーターなしのオブジェクトの合計数
  • Sub total: 検索パラメーターを指定して返されたオブジェクトの数（検索がない場合は、合計が合計と同じになります）。
  • page: ページ番号。
  • per_page: ページごとに返す最大オブジェクト数
  • limit: コレクションの応答で返すオブジェクトの指定数
  • offset: コレクションを返す前に省略するオブジェクト数
  • Search: scoped_scoped 構文をもとにした検索文字列
  • sort
    • by: コレクションがソートされるフィールド。
    • order: ソート順(ASC は昇順、DESC は降順)
  • 結果: オブジェクトのコレクション

単一オブジェクトの JSON 応答形式

単一オブジェクトの JSON 応答を使用して、単一のオブジェクトを表示します。GET リクエストには、オブジェクトの一意の識別子 :id または :name が必要です。:name は、常に一意の識別子として使用できませんが、:id を常に使用できます。単一オブジェクトの JSON 応答の形式は、オブジェクトの属性のみで設定されます。
以下は、API ルートの GET /api/domains/ 23 または GET /api/domains/ qa.lab.example.com を使用する場合の単一オブジェクト JSON 応答の形式例です。 
$ curl -X GET -k -u admin:password https://satellite6.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"
}
Copy to Clipboard Toggle word wrap
トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

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

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

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

会社概要

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

Theme

© 2025 Red Hat