Atlas Administration API を使い始める
項目一覧
- Atlas へのプログラムによるアクセスのための OAuth 2.0認証はプレビュー機能として利用できます。
- 機能および関連するドキュメントは、プレビュー期間中にいつでも変更される可能性があります。 OAuth2.0 認証を使用するには、Atlas Administration APIへのリクエストで使用する サービス アカウントを作成します。
重要
それぞれの Atlas Administration API には独自のリソースがあり、初期設定が必要です。
Atlas Administration API サーバーには、パブリックインターネットからのみアクセスできます。Atlas Administration API は、ネットワーク ピアリングまたはプライベート エンドポイントを使用する接続では使用できません。
詳細については、 「プログラムによる Atlas へのアクセス」を参照してください。
Atlas Administration API は、 REST アーキテクチャ スタイルの原則に従い、Atlas の機能へのプログラムによるアクセスを可能にする多数の内部リソースを公開します。詳細については、 Atlas Administration API リファレンスを参照してください。
Atlas へのプログラムによるアクセスの付与
次の 2 つの認証方法のいずれかを使用して、組織またはプロジェクトへのプログラムによるアクセスを許可できます。
API キー | サービス アカウント（プレビュー） |
|---|---|
HTTP ダイジェスト認証を使用する Atlas への認証のレガシー メソッド。 | 業界標準の OAuth 2.0 プロトコルとクライアント認証情報フローを使用して Atlas に認証する新しい方法。現在はプレビュー段階です。 |
Atlas は、ナンスと呼ばれる一意の値を使用して公開キーと秘密キーをハッシュします。ナンスは HTTP ダイジェスト認証仕様に従って、短期間のみ有効です。これはリプレイ攻撃を防ぐためのもので、ナンスをキャッシュして永久に使用することはできません。 | サービスアカウントを作成したら、そのクライアント ID とシークレットを使用してアクセス トークンを生成し、API リクエストを認証します。アクセス トークンは、OAuth 2.0 仕様に従って 1 時間（3600 秒）のみ有効です。アクセス トークンの有効期限が切れると、漏洩したアクセス トークンを時間制限なく使用できるようなリプレイ攻撃を防ぐことができます。 |
Atlas ロールは、API キーが実行できる操作を制限します。API キーで、エラーなく API エンドポイントを呼び出せるようにするには、ユーザーの場合と同様に API キーにロールを付与する必要があります。 | Atlas のロールは、サービスアカウントがアクセス トークンを使用して実行できる操作を制限します。アクセス トークンがエラーなしで API エンドポイントを呼び出せるように、ユーザーの場合と同様にサービスアカウントにロールを付与する必要があります。 |
Atlas は多くのリソースをプロジェクトにバインドします。 多くのAPIリソースURLは | Atlas は多くのリソースをプロジェクトにバインドします。 多くのAPIリソースURLは |
各 API キーは 1 つの組織のみに属しますが、その組織内の任意の数のプロジェクトに API キーによるアクセスを許可できます。 | 各サービスアカウントは 1 つの組織のみに属しますが、その組織内の任意の数のプロジェクトへのアクセスをサービスアカウントに許可できます。 |
API キーを使用して Atlas UI 経由で Atlas にログインすることはできません。 | サービスアカウントまたはそのアクセス トークンを使用して、Atlas UI から Atlas にログインすることはできません。 |
オプション: Atlas Administration API の IP アクセス リストを要求する
Atlas では、 IP アクセス リストが必要な場合を除き、インターネット上の任意のアドレスから Atlas Administration API リクエストを行うことができます。ただし、IP アクセス リストでは、IP アクセス リストで指定されたロケーションベースの IP アドレスまたは CIDR アドレスからの API リクエストのみに制限されます。
各認証方法には、独自のIP アクセス リストがあります。すべての Atlas Administration APIリクエストに IP アクセス リストが必要な場合は、API キーまたはサービスアカウントを使用して API リクエストを行う前に、 少なくとも 1 つのIP アクセス リストのエントリを定義する必要があります。
Atlas UI を使用して組織を作成すると、Atlas ではデフォルトで API アクセス リストの要求が有効になります。無効にするには、組織を作成するときに Require IP Access List for the Atlas Administration API を OFF に切り替えます。
組織の作成後、すべての Atlas Administration API リクエストに対して IP アクセス リストを要求するように組織を設定するには、次の手順を実行します。
Atlas で、Organization Settings ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
[Organizations] メニューの横にある [Organization Settings] アイコンをクリックします。
[ Organization Settings ]ページが表示されます。
組織へのプログラムによるアクセスの付与
API キーまたはサービスアカウントを使用して、プログラムによって組織へのアクセス権を付与するには、以下の手順を使用します。これら 2 つの認証方法の詳細については、「Atlas Administration API 認証」を参照してください。
重要
サービスアカウントは現在プレビュー段階です。詳細については、「サービスアカウントの概要」を参照してください。
必要なアクセス権
次のアクションを実行するには、Atlas に対する Organization Owner アクセス権が必要です。
API キーの作成
Atlas CLI を使用して組織で API キーを作成するには、次のコマンドを実行します。
atlas organizations apiKeys create [options]
コマンド構文とパラメーターの詳細については、Atlas CLI ドキュメントの「atlas organizations apiKeys create」を参照してください。
APIキーのAPIアクセス リスト エントリの追加
Atlas CLI を使用して API キーの IP アクセス リスト エントリを作成するには、次のコマンドを実行します。
atlas organizations apiKeys accessLists create [options]
コマンド構文とパラメーターの詳細については、Atlas CLI ドキュメントの「atlas organizations apiKeys accessLists create」を参照してください。
Atlas で、Organization Access Manager ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからOrganization Accessを選択します。
サイドバーの Access Manager をクリックします。
[ Organization Access Manager ]ページが表示されます。
API Key Information を入力します。
Descriptionと入力します。
Organization Permissions メニューで、API キーの新しいロールを選択します。
Atlas で、Organization Access Manager ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからOrganization Accessを選択します。
サイドバーの Access Manager をクリックします。
[ Organization Access Manager ]ページが表示されます。
サービスアカウント情報を入力します。
Nameと入力します。
Descriptionと入力します。
Client Secret Expiration メニューから期間を選択します。
[Organization Permissions] メニューから、サービスアカウントの新しいロールを選択します。
Atlas Administration API を使用して、組織のサービスアカウントを作成できます。
サービスアカウントを作成したら、出力から {CLIENT-ID} と {CLIENT-SECRET} をコピーして保存します。これは次の例のようになります。クライアント シークレットをすべて見ることができるのはこの時だけです。この情報は、API リクエストを行う際に必要になります。
{ "createdAt" : "2024-04-23T17:47:17Z", "description" : "Service account for my organization.", "clientId" : "{CLIENT-ID}", "name" : "My Service Account", "roles" : [ "ORG_MEMBER" ], "secrets" : [ { "createdAt" : "2024-04-23T17:47:17Z", "expiresAt" : "2024-12-01T00:00:00Z", "id" : "6627f7259d39d858378c9e30", "lastUsedAt" : null, "secret" : "{CLIENT-SECRET}" } ] }%
プロジェクトへのプログラムによるアクセスの付与
API キーまたはサービスアカウントのいずれかを使用して、プロジェクトへのプログラムによるアクセス権を許可するには、次の手順に従います。これら 2 つの認証方法の詳細については、「Atlas Administration API 認証」を参照してください。
重要
サービスアカウントは現在プレビュー段階です。詳細については、「サービスアカウントの概要」を参照してください。
必要なアクセス権
API キーにプロジェクトへのアクセス権を付与するには、そのプロジェクトに対する Project Owner アクセス権が必要です。
サービスアカウントにプロジェクトへのアクセス権を付与するには、そのプロジェクトを所有する組織への Organization Owner アクセス権が必要です。
プロジェクトへの既存の組織アクセス権の割り当て
組織に API キーまたはサービスアカウントをすでに作成している場合は、それらをプロジェクトに割り当てて、そのプロジェクトに Atlas Administration API へのアクセス権を付与できます。
Atlas CLI を使用してプロジェクトに API キーを割り当てるには、次のコマンドを実行します。
atlas projects apiKeys assign <ID> [options]
コマンド構文とパラメーターの詳細については、Atlas CLIドキュメントの「atlas projects apiKeys assign」を参照してください。
Atlas UI を使用して組織 API キーをプロジェクトに割り当てるには、次のようにします。
Atlas で、Project Access Manager ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
API キーをプロジェクトに追加します。
フィールドに公開キーを入力します。
Project Permissions メニューで、API キーの新しいロールを選択します。
警告
組織サービスアカウントをプロジェクトに割り当てると、Project Owner はシークレットのローテーションや IP アクセス リストの更新などを含め、サービスアカウントを管理できます。
Atlas で、Project Access Manager ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
プロジェクト ロールをサービスアカウントに割り当てます。
表示されるメニューで、サービスアカウントの新しいロールを選択します。
Atlas Administration API を使用して、既存のサービスアカウントにプロジェクトへのアクセス権を付与できます。
プロジェクトからのプロジェクト アクセス権の追加
組織に API キーまたはサービスアカウントをまだ作成していない場合は、プロジェクトにそれらを作成して、そのプロジェクトに Atlas Administration API へのアクセス権を付与できます。プロジェクトに対して作成した API キーまたはサービスアカウントは、権限 Organization Member を持つ親組織に自動的に追加されます。
Atlas CLI を使用してプロジェクトの API キーを作成するには、次のコマンドを実行します。
atlas projects apiKeys create [options]
コマンド構文とパラメーターの詳細については、Atlas CLI ドキュメントの「atlas projects apiKeys create」を参照してください。
プロジェクトの API キーを作成したら、Atlas UI を使用して API アクセスリストエントリを追加します。API アクセス リストを設定するまで、プロジェクトの API キーは使用できません。
注意
Atlas CLI の制限
Atlas CLI を使用してプロジェクト API キーの API アクセスリストを編集することはできません。
Atlas UI を使用して API アクセスリストのエントリを追加する場合
Atlas UI を使用してプロジェクトの API キーを作成する場合
Atlas で、Project Access Manager ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
API Key Information を入力します。
[Create API Key] ページで次を行います。
Descriptionと入力します。
Project Permissions メニューで、API キーの新しいロールを選択します。
Atlas UI を使用してプロジェクトのサービスアカウントを作成する場合
Atlas で、Project Access Manager ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
サービスアカウント情報を入力します。
Nameと入力します。
Descriptionと入力します。
Client Secret Expiration メニューから期間を選択します。
[Project Permissions（プロジェクト権限）] メニューから、サービスアカウントの新しいロールを選択します。
Atlas Administration API を使用して、プロジェクトのサービスアカウントを作成できます。
サービスアカウントを作成したら、出力から {CLIENT-ID} と {CLIENT-SECRET} をコピーして保存します。これは次の例のようになります。クライアント シークレットをすべて見ることができるのはこの時だけです。この情報は、API リクエストを行う際に必要になります。
{ "createdAt" : "2024-04-23T17:47:17Z", "description" : "Service account for my organization.", "clientId" : "{CLIENT-ID}", "name" : "My Service Account", "roles" : [ "ORG_MEMBER" ], "secrets" : [ { "createdAt" : "2024-04-23T17:47:17Z", "expiresAt" : "2024-12-01T00:00:00Z", "id" : "6627f7259d39d858378c9e30", "lastUsedAt" : null, "secret" : "{CLIENT-SECRET}" } ] }%
API リクエストを行う
Atlas Administration API は、API キーまたはサービスアカウントという 2 つの認証方法のいずれかを使用してリクエストを認証します。次の手順を完了するには、希望する認証方法を構成するときに保存したキーまたはシークレットが必要です。
重要
サービスアカウントは現在プレビュー段階です。詳細については、「サービスアカウントの概要」を参照してください。
すべての Atlas Administration API エンドポイントには次のベース URL があります。
https://cloud.mongodb.com/api/atlas/<version>
リクエストは次の例のようになります。ここで、{PUBLIC-KEY} は API 公開キー、{PRIVATE-KEY} は対応する秘密キーです。Atlas Administration API を通じて利用可能なエンドポイントを調べるには、MongoDB の Postman ワークスペースを使用できます。
次のサンプル GET リクエストは、組織内のすべてのプロジェクトを返します。
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2024-08-05+json" \ --include \ --request GET "https://cloud.mongodb.com/api/atlas/v2/groups"
次のサンプル POST リクエストは、リクエスト本文を受け取り、組織内に MyProject という名前のプロジェクトを作成します。
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2024-08-05+json" \ --include \ --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \ --data ' { "name": "MyProject", "orgId": "5a0a1e7e0f2912c554080adc" }'
サービスアカウントを使用して API リクエストを行うには、サービスアカウントを使用してアクセス トークンを生成し、そのアクセス トークンをリクエストで使用します。
サービスアカウントのクライアント シークレットを検索します。
サービスアカウントの作成直後に保存した、mdb_sa_sk_ で始まるクライアント シークレットを見つけます。クライアント シークレットを表示できるのは、このときだけです。クライアント シークレットを保存しなかった場合は、新しいクライアント シークレットを生成する必要があります。
アクセス トークンをリクエストします。
次の例の {BASE64-AUTH} を前のステップの出力に置き換え、実行します。
1 curl --request POST \ 2 --url https://cloud.mongodb.com/api/oauth/token \ 3 --header 'accept: application/json' \ 4 --header 'cache-control: no-cache' \ 5 --header 'authorization: Basic {BASE64-AUTH}' \ 6 --header 'content-type: application/x-www-form-urlencoded' \ 7 --data 'grant_type=client_credentials'
{"access_token":"eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImYyZjE2YmE4LTkwYjUtNDRlZS1iMWYwLTRkNWE2OTllYzVhNyJ9.eyJpc3MiOiJodHRwczovL2Nsb3VkLWRldi5tb25nb2RiLmNvbSIsImF1ZCI6ImFwaTovL2FkbWluIiwic3ViIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImNpZCI6Im1kYl9zYV9pZF82NjI4MWJjNjAzYTcxYTQzMGI5MDZlZjciLCJhY3RvcklkIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImlhdCI6MTcxMzkwNTM1OSwiZXhwIjoxNzEzOTA4OTU5LCJqdGkiOiI4ZTg1MTM3YS0wZGU1LTQ0N2YtYTA0OS1hMmVmNTIwZGJhNTIifQ.AZSFvhcjwVcJYmvW6E_K5UnDmeiX2sJgL27vo5ElzeBuPawRciKkn6ervZ6IpUTx2HHllGgAAMmhaP9B66NywhfjAXC697X9KcOzm81DTtvDjLrFeRSc_3vFmeGvfUKKXljEdWBnbmwCwtBlO5SJuBxb1V5swAl-Sbq9Ymo4NbyepSnF","expires_in":3600,"token_type":"Bearer"}%
重要
アクセス トークンは 1 時間（3600 秒）有効です。アクセス トークンを更新することはできません。このアクセス トークンの有効期限が切れたら、この手順を繰り返して新しいアクセス トークンを生成します。
API 呼び出しを行います。
次の例の {ACCESS-TOKEN} を前のステップの出力に置き換えます。
次のサンプル GET リクエストは、組織内のすべてのプロジェクトを返します。
curl --request GET \ --url https://cloud.mongodb.com/api/atlas/v2/groups \ --header 'Authorization: Bearer {ACCESS-TOKEN}' \ --header 'Accept: application/vnd.atlas.2023-02-01+json' \ --header 'Content-Type: application/json'
次のサンプル POST リクエストは、リクエスト本文を受け取り、組織内に MyProject という名前のプロジェクトを作成します。
curl --header 'Authorization: Bearer {ACCESS-TOKEN}' \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2023-02-01+json" \ --include \ --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \ --data ' { "name": "MyProject", "orgId": "5a0a1e7e0f2912c554080adc" }'
あるいは、OpenAPI v3 仕様 をサポートする任意のツールを使用して、コードサンプルやモック サーバーを生成することもできます。たとえば、Atlas Admin API 仕様をPostman にインポートして curl コマンドを生成できます。Postman を使用して curl コマンドを生成するには、次のようにします。
MongoDB Atlas Administration API ドキュメント で、[Download（ダウンロード）] ボタンを右クリックしてリンクをコピーします。
次のステップ
Atlas Administration API の詳細については、「Atlas Administration API リファレンス」を参照してください。
プログラムによる Atlas Administration API へのアクセスを管理するには、次のいずれかの手順を参照してください。