第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

HTTP_VERB API_ROUTE

Copy to Clipboard

Toggle word wrap

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

curl --request HTTP_VERB \
--insecure \
--user sat_username:sat_password \
--data @file.json \
--header "Accept:application/json,version=2" \
--header "Content-Type:application/json" \
--output file

$ curl --request HTTP_VERB \


--insecure \


--user sat_username:sat_password \


--data @file.json \


--header "Accept:application/json,version=2" \


--header "Content-Type:application/json" \


--output file


API_ROUTE \


| python -m json.tool

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

応答例:

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

{
  "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 つ、これらは結果の 1 ページ目に表示され、ページごとの最大結果数は 20 に設定されていることが分かります。詳しい情報は「JSON 応答形式の理解」を参照してください。

2.1.2. HTTP 動詞 (POST) の使用
リンクのコピー

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

例

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

以下のコンテンツを含めて、activation-key.json などのテストファイルを作成します。
```
{"organization_id":1, "name":"TestKey", "description":"Just for testing"}
```
```
{"organization_id":1, "name":"TestKey", "description":"Just for testing"}
```
Copy to Clipboard Toggle word wrap

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

$ 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

Copy to Clipboard

Toggle word wrap

応答例:

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

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

新しいアクティベーションキーが存在することを確認します。Satellite Web UI で、コンテンツ > アクティベーションキー に移動して、アクティベーションキーを表示します。

2.1.3. HTTP 動詞 (PUT) の使用
リンクのコピー

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

例

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

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

{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }

{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }

Copy to Clipboard

Toggle word wrap

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

$ 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

Copy to Clipboard

Toggle word wrap

応答例:

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

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

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

$ 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

Copy to Clipboard

Toggle word wrap

応答例:

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

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

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

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

Nested_Resource.Attribute_Name

Nested_Resource.Attribute_Name

Copy to Clipboard

Toggle word wrap

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

Resource[Nested_Resource_attributes][Attribute_Name_id]

Resource[Nested_Resource_attributes][Attribute_Name_id]

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

応答例:

{
    "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": 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

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

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

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

要求例:

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

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

Copy to Clipboard

Toggle word wrap

応答例:

{
    "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": 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

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

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

total: 検索パラメーターなしのオブジェクトの合計数
subtotal: 検索パラメーターを指定して返されたオブジェクト数 (検索がない場合には、累計は合計と同じになります)
page: ページ数
per_page: ページごとに返す最大オブジェクト数
limit: コレクションの応答で返すオブジェクトの指定数
offset: コレクションを返す前に省略するオブジェクト数
search: scoped_scoped 構文をもとにした検索文字列
sort
- by: API がコレクションをソートするフィールド別に指定します。
- order」: ソート順 (ASC は昇順、DESC は降順)
results: オブジェクトのコレクション

第2章 API リファレンス

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

2.1.1. HTTP 動詞 (GET) の使用
リンクのコピー

2.1.2. HTTP 動詞 (POST) の使用
リンクのコピー

2.1.3. HTTP 動詞 (PUT) の使用
リンクのコピー

2.1.4. HTTP 動詞 (DELETE) の使用
リンクのコピー

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

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

詳細情報

試用、購入および販売

コミュニティー

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

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

会社概要

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

第2章 API リファレンス

2.1. API 構文の理解リンクのコピーリンクがクリップボードにコピーされました!

2.1.1. HTTP 動詞 (GET) の使用リンクのコピーリンクがクリップボードにコピーされました!

2.1.2. HTTP 動詞 (POST) の使用リンクのコピーリンクがクリップボードにコピーされました!

2.1.3. HTTP 動詞 (PUT) の使用リンクのコピーリンクがクリップボードにコピーされました!

2.1.4. HTTP 動詞 (DELETE) の使用リンクのコピーリンクがクリップボードにコピーされました!

2.1.5. API エラーメッセージと API リファレンスの関連付けリンクのコピーリンクがクリップボードにコピーされました!

2.2. JSON 応答形式の理解リンクのコピーリンクがクリップボードにコピーされました!

詳細情報

試用、購入および販売

コミュニティー

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

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

会社概要

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

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

2.1.1. HTTP 動詞 (GET) の使用
リンクのコピー

2.1.2. HTTP 動詞 (POST) の使用
リンクのコピー

2.1.3. HTTP 動詞 (PUT) の使用
リンクのコピー

2.1.4. HTTP 動詞 (DELETE) の使用
リンクのコピー

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

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