第2章 API リファレンス

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

2.1. API 構文の理解

注記

以下の要求例では、python3 を使用して Satellite Server からの応答をフォーマットしています。RHEL 7 およびそれ以前の一部のシステムでは、python3 の代わりに python を使用する必要があります。

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" \ 5
--header "Content-Type:application/json" \      6
--output file                                  7
API_ROUTE \                                    8
| python3 -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 | python3 -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" \
    --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 \
    | python3 -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" \
    --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 \
    | python3 -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" \
--header "Content-Type:application/json" --request DELETE \
--user sat_username:sat_password --insecure \
https://satellite.example.com/katello/api/activation_keys/2 \
| python3 -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]