第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

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...]

が表示されます。本ガイドで使用するオプションには -X、--request コマンド が含まれます。ここでの 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 のみをサポートし、一部の認証形式が必要です。

使用可能な例として、少なくとも 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

API からの上記の応答により合計 2 つの結果が返され、以下のような 2 つの結果が返されたこと、これは結果の 1 ページ目で、ページごとの最大結果数は 20 に設定されていることが分かります。これについては、「JSON 応答形式の理解」で詳細に説明されています。

API リファレンスの例には、:パラメーターの前にコロンが付いた用語が含まれています。たとえば、

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 @ファイル.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

または、json_reformat ツールを使用してください。

curl API_call | json_reformat

出力形式については、「JSON 応答形式の理解」で説明されています。

API リファレンスには、アクティベーションキーセクションに以下が含まれます。

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
    }
}

Web UI でこのエントリーを表示するには、コンテンツ

アクティベーションキーに移動します。変更後は、必ずページを再読み込みしてください。

HTTP 動詞 (PUT) の使用

HTTP 動詞の PUT は、データを API に送信して、既存のエントリーまたはリソースを更新するために使用されます。POST API 呼び出しと同様に、データは JSON 形式である必要があり、

d, --data オプションの後に中かっこ {} で囲まれた引用符で囲まれた 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
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

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

API はエラーの表示に RAILS 形式を使用します。

Nested_Resource.Attribute_Name

これは、以下のように、API リファレンスで使用する形式に変換されます。

Resource[Nested_Resource_attributes][Attribute_Name_id]

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"
        }
    ]
}

応答のメタデータのフィールドの説明は以下のとおりです。

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"
}

第2章 API リファレンス

2.1. API 構文の理解

HTTP 動詞 (GET) の使用

HTTP 動詞 (POST) の使用

HTTP 動詞 (PUT) の使用

HTTP 動詞 (DELETE) の使用

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

2.2. JSON 応答形式の理解

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

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

詳細情報

試用、購入および販売

コミュニティー

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

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

会社概要

Red Hat legal and privacy links

Red Hat legal and privacy links