第2章 API リファレンス

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

2.1. API 構文の理解

Satellite に含まれている API リファレンスは、HTTP 動詞の後に API ルートまたはパスを記載します。

HTTP_VERB API_ROUTE

API を使用するには、curl コマンド構文と当リファレンスドキュメントの API ルートを使用して、コマンドを構築します。

$ curl --request HTTP_VERB \                   1
--insecure \                                   2
--user sat_username:sat_password \             3
--data @file.json \                            4
--header "Accept:application/json,version=2" \ 5
--header "Content-Type:application/json" \      6
--output file                                  7
API_ROUTE \                                    8
| python -m json.tool                          9
1
API 呼び出しに curl を使用するには、HTTP 動詞に --request オプションを指定します (例: --request POST)。
2
--insecure オプションを追加して、SSL ピア証明書の検証確認をスキップします。
3
--user オプションを使用してユーザー認証を指定します。
4
POST および PUT 要求の場合は、--data オプションを使用して、JSON 形式のデータを渡します。詳細情報は、「API 要求への JSON データの指定」を参照してください。
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 モジュールに出力をリダイレクトして、出力の可読性を向上します。

2.1.1. HTTP 動詞 (GET) の使用

HTTP 動詞 (GET) を使用して、既存のエントリーまたはリソースに関するデータを API から取得します。

この例では、Satellite ホストの数を要求します。

要求例:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/hosts | python -m json.tool

応答例:

{
  "total": 2,
  "subtotal": 2,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results":
output truncated

API からの応答により、結果数が合計 2 つ、これらは結果の 1 ページ目に表示され、ページごとの最大結果数は 20 に設定されていることが分かります。詳しい情報は「JSON 応答形式の理解」を参照してください。

2.1.2. HTTP 動詞 (POST) の使用

HTTP 動詞 (POST) を使用して、データを API に送信してエントリーまたはリソースを作成します。JSON 形式でデータを送信する必要があります。詳細情報は、「API 要求への JSON データの指定」を参照してください。

この例では、アクティベーションキーを作成します。

  1. 以下のコンテンツを含めて、activation-key.json などのテストファイルを作成します。

    {"organization_id":1, "name":"TestKey", "description":"Just for testing"}
  2. activation-key.json ファイルにデータを適用してアクティベーションキーを作成します。

    要求例:

    $ curl --header "Accept:application/json,version=2" \
    --header "Content-Type:application/json" --request POST \
    --user sat_username:sat_password --insecure \
    --data @activation-key.json \
    https://satellite.example.com/katello/api/activation_keys \
    | python -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
        }
    }
  3. 新しいアクティベーションキーが存在することを確認します。Satellite Web UI で、コンテンツ > アクティベーションキー に移動して、アクティベーションキーを表示します。

2.1.3. HTTP 動詞 (PUT) の使用

HTTP 動詞 (PUT) を使用して、既存の値を変更するか、既存のリソースに追加します。JSON 形式でデータを送信する必要があります。詳細情報は、「API 要求への JSON データの指定」を参照してください。

この例では、1 つ前の例で作成した TestKey アクティベーションキーを更新します。

  1. 先ほど作成した activation-key.json ファイルを以下のように編集します。

    {"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }
  2. JSON ファイルの変更を適用します。

    要求例:

    $ curl --header "Accept:application/json,version=2" \
    --header "Content-Type:application/json" --request PUT \
    --user sat_username:sat_password --insecure \
    --data @activation-key.json \
    https://satellite.example.com/katello/api/activation_keys/2 \
    | python -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
        }
    }
  3. Satellite Web UI で、コンテンツ > アクティベーションキー に移動して、変更を確認します。

2.1.4. HTTP 動詞 (DELETE) の使用

リソースを削除するには、削除するリソース ID を含む API ルートと DELETE 動詞を使用します。

この例では、ID が 2 の TestKey アクティベーションキーを削除します。

要求例:

$ curl --header "Accept:application/json,version=2" \
--header "Content-Type:application/json" --request DELETE \
--user sat_username:sat_password --insecure \
https://satellite.example.com/katello/api/activation_keys/2 \
| python -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

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

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

Nested_Resource.Attribute_Name

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

Resource[Nested_Resource_attributes][Attribute_Name_id]

2.2. JSON 応答形式の理解

API への呼び出しは、JSON 形式の結果を返します。API 呼び出しは、単一オプションの応答または、応答コレクションの結果を返します。

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

単一オブジェクトで作業するには、単一オブジェクトの JSON 応答を使用します。単一のオブジェクトに対する API 要求では、オブジェクトの一位識別子 :id が必要です。

これは、ID が 23 の Satellite ドメインに対する単一オブジェクトの形式例です。

要求例:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.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"
}

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

コレクションは、ホストとドメインなどのオブジェクト一覧です。JSON 応答コレクションの形式は、メタデータのフィールドセクションと結果セクションで構成されます。

以下は、Satellite ドメイン一覧のコレクション要求の形式例です。

要求例:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.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"
        }
    ]
}

応答メタデータフィールド

API 応答は、以下のメタデータフィールドを使用します。

  • total: 検索パラメーターなしのオブジェクトの合計数
  • subtotal: 検索パラメーターを指定して返されたオブジェクト数 (検索がない場合には、累計は合計と同じになります)
  • page: ページ数
  • per_page: ページごとに返す最大オブジェクト数
  • limit: コレクションの応答で返すオブジェクトの指定数
  • offset: コレクションを返す前に省略するオブジェクト数
  • search: scoped_scoped 構文をもとにした検索文字列
  • sort

    • by: API がコレクションをソートするフィールド別に指定
    • order: ソート順 (ASC は昇順、DESC は降順)
  • results: オブジェクトのコレクション