Red Hat Subscription Management での API の使用

Subscription Central 1-latest

Subscription Management API の認可、管理、およびトラブルシューティング

Customer Content Services

概要

Red Hat サブスクリプションサービスは、Red Hat 製品に対するサブスクリプションの自動化、管理、追跡に役立つ開発および文書化された API を提供します。

1. Red Hat Subscription Management での API の使用

サブスクリプションサービスで API を使用すると、次の方法で Red Hat サブスクリプションの使用状況をより効果的に追跡し、自動化できます。

  • 各製品に使用するツールを制御する
  • システムとサブスクリプションのインベントリーをより適切に管理する
  • システムの更新とセキュリティー保護を効率化する
  • Red Hat 製品の正式サポートを継続して受ける

Red Hat Subscription Management API は認可に OAuth 2.0 を使用します。トークンを取得し、API にアクセスするには、以下の情報が必要になります。

2. 認証でのトークンの使用

オフライントークンと更新トークンは、シークレットを使用して Red Hat Single Sign On (SSO) アカウントを認証し、アカウントをセットアップした後に、システムを認証するために Red Hat Subscription Management によって使用されます。

警告

セキュリティーのベストプラクティスに沿ったパスワード管理を使用してください。パスワードや認証情報をプレーンテキストに保存するのは危険です。オフライントークンには、パスワードを不正使用から保護するためのセキュリティー対策を同じように適用してください。

2.1. 新しいオフライントークンの生成

オフライントークンは、30 日ごとに最低 1 回使用し、Red Hat Subscription Managemer API のアクセストークンを作成する場合に限り、有効期限が切れることはありません。これはパスワードとして機能し、新しい更新トークンを作成せずに引き続きアカウントを認証できます。

手順

  1. Red Hat Subscription Manager API Tokens のページ にアクセスします。
  2. Generate Token ボタンをクリックします。

2.2. 新しい更新トークンの生成

オフライントークンを作成したら、そのトークンを使用して新しい更新トークンを作成できます。これには 5 分間有効なアクセストークンが含まれます。アクセストークンは、カスタマーポータルのユーザーアカウントを Red Hat Subscription Manager API に対して認証するためにヘッダーで使用されます。

手順

  1. オフラインのトークン値を設定します。この例では、分かりやすくするためにプレーンテキストで設定し、トークンの値を短くしています。

    # offline_token='eyJhbGciOiJSUzI1NiIsInR5cCIgOiA'
  2. 次のコマンドを入力して、JSON 値を簡単にフィルターする関数を作成します。

    # function jsonValue() {
    KEY=$1
    num=$2
    awk -F"[,:}]" '{for(i=1;i<=NF;i++){if($i~/'$KEY'\042/){print $(i+1)}}}' | tr -d '"' | sed -n ${num}p
    }
  3. 次のコマンドを入力して、access_token を抽出します。

    # curl https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token -d grant_type=refresh_token -d client_id=rhsm-api -d refresh_token=$offline_token

    予想される出力は次のようになります。ここで、access_token はアカウントの認可に使用されるトークンです。

    {"access_token":"oiZjo1MjhkNzZmZi1mNzA4LTQzZWQtOGNkNS1mZTE2ZjRmZTBjZTY6cmhuLXN1cHBvcnQta3RvcmRldXIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJyaHNtLWFwaSIsImF1dGhfdGltZSI6MTU2NzQwODU5Nywic2Vzc2lvbl9zdGF0ZSI6ImYwZGJiOGQ0LTRlNGUtNDY1NC04NDRjLTZmMzcwNGM4NDQyMiIsImFjciI6IjAiLCJhbGxvd2VkLW9yaWdpbnMiOltdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsicG9ydGFsX21hbmFnZV9zdWJzY3JpcHRpb25zIiwib2ZmbGluZV9hY2Nlc3MiLCJjYW5kbGVwaW5fc3lzdGVtX2FjY2Vzc192aWV3X2VkaXRfYWxsIiwiYWRtaW46b3JnOmFsbCIsInBvcnRhbF9tYW5hZ2VfY2FzZXMiLCJwb3J0YWxfc3lzdGVtX21hbmFnZW1lbnQiLCJwb3J0YWxfZG93bmxvYWQiXX0sInJlc291cmNlX2FjY2VzcyI6e30sImFjY291bnRfaWQiOiIxOTc5NzEwIiwibmFtZSI6Iktlbm55IFRvcmRldXJzIiwicHJlZmVycmVkX3VzZXJuYW1lIjoicmhuLXN1cHBvcnQta3RvcmRldXIiLCJnaXZlbl9uYW1lIjoiS2VubnkiLCJmYW1pbHlfbmFtZSI6IlRvcmRldXJzIiwiZW1haWwiOiJrdG9yZGV1ckByZWRoYXQuY29tIn0.JfStOgLvgFUAlMb7aVfm-dWxd4wN5oqk377Q6oyDe55pM4zDiZ0f1yJfHsWL8RHeb3r0tj8DY_UAyAFkxAnjyWjq52d7h2EfJUPOs1p1P8Yeu5hDwOrA34Es2maN-ZbJCc4sOb7stGhxSCU15CfvPFIRR5tgSQ17-Mx-x4ZnK_fwpOK6DqQpNzZ0Krz3U1a-NH86XJ8dT8lC3o03YrdlcZx_-wv6-PehqNQa2Hb9vt1csX8QlL3PEyBVNPZXaaTHvyFYx0orGyjKA83Qq-LihbWBXzNjf_rIEfsPJYi-uQHIT_zjaOPYo2rXi7VTPJC2qRSxF2yaRGlihZHxkDzMOTITnaDeMhbx1zvRr-R9eXocEUzsU9j-Yx7h3WYCFjb8zdfXTBHV8SCaMdH1u9Eesa5gmHOoki8882RR85i1fjpBayFTS36y4S-yDebUYiukXOnw8mMMKy04NhVpFGfWtJ8--Jy4Ypndqqk_OS_PiWBsFFN6lMv5S6DZWVpjjE-CENHKn9ceA4MlerBBXLY02Xz9h0biiQUZrd-NLy11j4os124Mai1mmlNOLz993hw0gl-vKKno_bYOV8dEEmKtSLlSPVdW5X_0vBU0BtQuSEVctz_8zsRKHpT-YlDdmP0VDuzJjWM0YsGz2W0_tMuLG7NYS_Ia3vWAVuK--Uv5cAQ","expires_in":900,"refresh_expires_in":0,"refresh_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICItNGVsY19WZE5fV3NPVVlmMkc0UXhyOEdjd0l4X0t0WFVDaXRhdExLbEx3In0.eyJqdGkiOiJhODZlZDczZS00MmE1LTQzYjUtYjJkYS1iMWM5NzU3OWUyZWMiLCJleHAiOjAsIm5iZiI6MCwiaWF0IjoxNTY3NDEwMDIxLCJpc3MiOiJodHRwczovL3Nzby5yZWRoYXQuY29tL2F1dGgvcmVhbG1zL3JlZGhhdC1leHRlcm5hbCIsImF1ZCI6InJoc20tYXBpIiwic3ViIjoiZjo1MjhkNzZmZi1mNzA4LTQzZWQtOGNkNS1mZTE2ZjRmZTBjZTY6cmhuLXN1cHBvcnQta3RvcmRldXIiLCJ0eXAiOiJPZmZsaW5lIiwiYXpwIjoicmhzbS1hcGkiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJmMGRiYjhkNC00ZTRlLTQ2NTQtODQ0Yy02ZjM3MDRjODQ0MjIiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsicG9ydGFsX21hbmFnZV9zdWJzY3JpcHRpb25zIiwib2ZmbGluZV9hY2Nlc3MiLCJjYW5kbGVwaW5fc3lzdGVtX2FjY2Vzc192aWV3X2VkaXRfYWxsIiwiYWRtaW46b3JnOmFsbCIsInBvcnRhbF9tYW5hZ2VfY2FzZXMiLCJwb3J0YWxfc3lzdGVtX21hbmFnZW1lbnQiLCJwb3J0YWxfZG93bmxvYWQiXX0sInJlc291cmNlX2FjY2VzcyI6e319.S_pmAWzQUc04f0uGHN9rRYd4sH1t4IPnEwCcOH1aBL9Qo4_EbXPWCrtnf84f1pfuKJTQwUS-DldY6eloyVEsGgnqkygBKh270bu_bNXCNAuLJigEMsYx_2VzdnwWLptWS2_FUaNwe7Tai8qXwd8F0ge0Zjoi3P15S_8z4Tp79uD-qKcvwz6NlPKCOZwEbwZqOkJDZ8JKTIK8O0jfqdtHMfaWwlXMXdvx3B70tTOtHjQGAsxZA2dPPvqVGuyMOMmC3bMaISReUbtDwsCV-eAZplDfDZthr4k4JbmG9Iwq1aATaF3aCwfpebcmoIZGHE4_RLZrXCZKapXVVvRxcOrJytxIZrbDHq6ozX7j-j1SE3kuexcSLvlodmfTlxwPX9g7aqJu2ZLno54NxQSgYO8lQqSvScFgLtbX5f_FUS0Iw6yRWWJy2o2fnvfGk83rt5UYTtIb8Xd1GXcpHf8Yl10nVy21BetSQY__VpahF_eZghBNxS689GJnwUqAwlu01pOlb26mmHaydHc3hqUsudZydRbaFfI7nR6gQP8lCtp6b0z5hgVHLG4ZJ7i4MmEL6C5G4xHUaUs6RZgJUSsc2DzLW0b7rSQj41JuvTmSgD8bMrnVokmkAbfvxjKGc7E8n2GyImO7JiKb3RA7_o0xOTRYDIa_Ns-lnigJkUlQZUzt7JI","token_type":"bearer","not-before-policy":0,"session_state":"f0dbb8d4-4e4e-4654-844c-6f3704c84422","scope":"offline_access"}%
  4. 次のコマンドを入力して、API 呼び出しの実行に使用できる認可トークンとして access_token を設定します。

    # token=`curl https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token -d grant_type=refresh_token -d client_id=rhsm-api -d refresh_token=$offline_token | jsonValue access_token`

3. 利用可能な Subscription Management API へのアクセス

Red Hat は、Red Hat Subscription Management API の仕様を記述する Swagger ファイルを提供します。Swagger 仕様には、利用可能な API エンドポイント、入力パラメーター、想定される出力、考えられるエラー応答に関する情報が含まれます。swagger ファイルは、Postman や RESTlet と同様に REST クライアントにインポートでき、API 呼び出しのライブラリーを自動的にビルドします。

4. API エラーのトラブルシューティング

表1 API エラー

コード説明解決方法

400

BadRequest エラー

API 呼び出しを正しく入力し、再度検証。

401

認可されていない

新しい認可トークンを生成。

403

禁止されている

新しい認可トークンを生成。

404

見つからない

リソースが見つからないか、存在しない。

429

要求が多すぎる

要求頻度を減らす。

500

内部サーバーエラー

この問題は、Red Hat サイトで発生。1 分待ってから再要求。

4.1. エラー 403 のトラブルシューティング

エラー 403 は認可されていないというエラーで、Red Hat Subscription Manager API に使用している認証が失敗したことを意味します。試すことができる解決策は 2 つあります。

手順

  1. Red Hat サブスクリプションマネージャーのゲートウェイ経由で認証を行うには、API 呼び出しを入力する前に、認証ヘッダーに "bearer" のテキストが含まれるようにします。

    curl -H "Authorization: Bearer <token>" <api_url>
  2. ヘッダーが正しい場合は、新しいトークンを作成します。更新トークンは 5 分間持続します。

4.2. エラー 429 のトラブルシューティング

エラー 429 は帯域制限エラーです。つまり、お使いのアカウントで 1 秒間で許容される要求の数を超えています。この制限は、1 つの Red Hat アカウントに含まれるすべてのユーザーに適用されます。

手順

レスポンスのヘッダーを抽出します。これには、* X-RateLimit-Limit: (許可される要求の合計/秒) * X-RateLimit-Remaining: (要求の数/残りの秒 (これは負の整数になります)) * X-RateLimit-Delay: (リクエスターが再試行するまで待機する秒数) が含まれます。

X-RateLimit-Limit 値に対する要求の帯域を調整し、X-RateLimit-Delay 時間が経過したら再度開始します。

法律上の通知

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.