|
この文書は自動機械翻訳技術を使用して翻訳されています。 正確な翻訳を提供するように努めておりますが、翻訳された内容の完全性、正確性、信頼性については一切保証いたしません。 相違がある場合は、元の英語版 英語 が優先され、正式なテキストとなります。 |
以前のv3 SUSE Rancher Prime API ガイド
|
The v3 API is not supported and backwards compatibility is not guaranteed. |
Rancher v2.8.0では、RancherがサポートするAPIであるRancher Kubernetes API（RK-API）が導入されました。このページでは、v3 APIについて説明します。RK-APIの詳細については、RK-APIクイックスタートおよびリファレンスガイドを参照してください。
APIの使用方法
以前のv3 APIには、ウェブブラウザからアクセスできる独自のユーザーインターフェースがあります。これは、リソースを表示し、アクションを実行し、同等の`curl`またはHTTPリクエストとレスポンスを確認する簡単な方法です。アクセスするには：
-
右上隅のユーザーアバターをクリックします。
-
*アカウントとAPIキー*をクリックします。
-
*APIキー*セクションの下で、*APIエンドポイント*フィールドを見つけてリンクをクリックします。リンクは`\https://<rancher_fqdn>/v3`のように見え、`<RANCHER_FQDN>`はRancherデプロイメントの完全修飾ドメイン名です。
認証
APIリクエストには認証情報を含める必要があります。認証は、rancher-admin/users/settings/api-keys.adoc[APIキー]を使用したHTTP基本認証で行われます。APIキーは新しいクラスターを作成でき、`/v3/clusters/`を介して複数のクラスターにアクセスできます。クラスターおよびプロジェクトの役割はこれらのキーに適用され、アカウントが見ることができるクラスターとプロジェクト、及び実行できるアクションを制限します。
デフォルトでは、特定のクラスター レベルのAPI トークンが無期限の有効期限で生成されます（ttl=0）。言い換えれば、`ttl=0`が設定されているAPIトークンは、無効にしない限り期限切れになりません。それらを無効にする方法の詳細については、APIトークンページを参照してください。
リクエストの作成
APIは一般的にRESTfulですが、すべての定義をクライアントが発見できるようにするためのいくつかの機能があり、特定のリソースタイプごとに特定のコードを書く必要がなく、汎用クライアントを作成できるようにしています。汎用API仕様に関する詳細情報は、 さらに文書を参照してください。
-
すべてのタイプには、次のことを説明するスキーマがあります：
-
このタイプのリソースのコレクションにアクセスするためのURL。
-
リソースが持つ可能性のあるすべてのフィールド、そのタイプ、基本的な検証ルール、必須かオプションかなど。
-
このタイプのリソースに対して可能なすべてのアクション、その入力と出力（スキーマとして）。
-
フィルタリングを許可するすべてのフィールド。
-
コレクション自体、またはコレクション内の個々のリソースに対して利用可能なHTTP動詞メソッド。
-
この設計により、スキーマのリストを読み込むだけでAPIに関するすべてにアクセスできます。APIのUIには、Rancher自体に特有のコードは含まれていません。スキーマを取得するためのURLは、すべてのHTTPレスポンスに`X-Api-Schemas`ヘッダーとして送信されます。そこから、各スキーマの`collection`リンクをたどってリソースをリストする場所を知り、返されたリソース内の他の`links`をたどって他の情報を取得できます。
実際には、URL文字列を構築したいだけかもしれません。これをトップレベルに制限することを強くお勧めします（コレクションをリストするための`/v3/<type>`または特定のリソースを取得するための`/v3/<type>/<id>`）。それ以上の深さは、将来のリリースで変更される可能性があります。
リソース間にはリンクと呼ばれる関係があります。各リソースには、リンクの名前とその情報を取得できるURLを含む`links`のマップが含まれています。再度、リソースを`GET`し、`links`マップ内のURLをたどるべきであり、これらの文字列を自分で構築すべきではありません。
ほとんどのリソースには、何かを行ったりリソースの状態を変更したりするアクションがあります。それらを使用するには、希望するアクションの`actions`マップ内のURLにHTTP`POST`を送信してください。特定のアクションには入力が必要であったり、出力を生成したりします。各タイプごとの個別ドキュメントや、特定の情報については、スキーマを参照してください。
リソースを編集するには、変更したいフィールドを含むリソースの links.update リンクに HTTP PUT を送信してください。リンクが欠けている場合は、リソースを更新する権限がありません。不明なフィールドや編集できないフィールドは無視されます。
リソースを削除するには、リソースの links.remove リンクに HTTP DELETE を送信してください。リンクが欠けている場合は、リソースを更新する権限がありません。
新しいリソースを作成するには、スキーマ内のコレクション URL に HTTP POST を送信します（これは /v3/<type> です）。
フィルタ
ほとんどのコレクションは、HTTP クエリパラメータを使用してサーバー側で一般的なフィールドでフィルタリングできます。filters マップは、フィルタリング可能なフィールドと、あなたが行ったリクエストのフィルタリングされた値を示します。API UI には、フィルタリングを設定し、適切なリクエストを表示するためのコントロールがあります。単純な「等しい」マッチの場合は、単に field=value です。修飾子はフィールド名に追加できます。たとえば、field_gt=42 は「フィールドが 42 より大きい」です。詳細については、 API 仕様 を参照してください。
[Sorting]
ほとんどのコレクションは、HTTP クエリパラメータを使用してサーバー側で一般的なフィールドでソートできます。sortLinks マップは、利用可能なソートの種類と、それぞれのソートでコレクションを取得するためのURLを示します。また、指定されている場合は、現在のレスポンスがどのソート順で並べ替えられているかに関する情報も含まれています。
ページ番号付け
APIのレスポンスは、デフォルトで1ページあたり100件のリソースに制限されてページネーションされます。これは`limit`クエリパラメータで変更でき、最大1,000まで設定可能です。例えば、`/v3/pods?limit=1000`のように指定します。コレクションレスポンスの`pagination`マップは、完全な結果セットが含まれているかどうかを示し、含まれていない場合は次のページへのリンクを提供します。
v3 API コールのキャプチャ
ブラウザの開発者ツールを使用して、v3 API がどのように呼び出されるかをキャプチャできます。たとえば、Chrome の開発者ツールを使用して Rancher Kubernetes ディストリビューションクラスターのプロビジョニングのための API コールを取得するには、次の手順に従うことができます:
-
Rancher UIで、*クラスター管理*に移動し、*作成*をクリックします。
-
クラスタータイプのいずれかをクリックします。この例ではDigital Oceanを使用します。
-
クラスター名とノードテンプレートを入力しますが、*作成*をクリックしないでください。
-
クラスター作成前にAPIコールが記録されるのを見るために、開発者ツールを開く必要があります。ツールを開くには、Rancher UIを右クリックし、*検査*をクリックします。
-
開発者ツールで、*ネットワーク*タブをクリックします。
-
*ネットワーク*タブで、*Fetch/XHR*が選択されていることを確認します。
-
Rancher UIで、*作成*をクリックします。開発者ツールで、`cluster?_replace=true`という名前の新しいネットワークリクエストが表示されるはずです。
-
`cluster?_replace=true`を右クリックし、menu:コピー[cURLとしてコピー]をクリックします。
-
結果を任意のテキストエディタに貼り付けます。送信先のURL、すべてのヘッダー、およびリクエストの完全なボディを含むPOSTリクエストを見ることができます。このコマンドは、コマンドラインからクラスターを作成するために使用できます。注意: リクエストには資格情報が含まれているため、安全な場所に保存する必要があります。