Atlas Administration API を使い始める
項目一覧
重要
それぞれの Atlas Administration API には独自のリソースがあり、初期設定が必要です。
Atlas Administration API サーバーには、パブリック インターネット経由でのみアクセスできます。ネットワーク ピアリングやプライベートエンドポイントを使用した接続では Atlas Administration API を利用できません。
詳細については、 「プログラムによる Atlas へのアクセス」を参照してください。
Atlas Administration API は、 REST アーキテクチャ スタイルの原則に従い、Atlas の機能へのプログラムによるアクセスを可能にする多数の内部リソースを公開します。詳細については、 Atlas Administration API リファレンスを参照してください。
Atlas へのプログラムによるアクセスの付与
次の 2 つの認証方法のいずれかを使用して、組織またはプロジェクトへのプログラムによるアクセスを許可できます。
サービス アカウント | API キー |
|---|---|
業界標準の OAuth 2.0 プロトコルを使用し、 クライアント認証情報フロー を使用して Atlas に認証する新しい方法。 | HTTPダイジェスト認証を使用する Atlas へのレガシー認証方法。 |
サービスアカウントを作成したら、そのクライアント ID とシークレットを使用してアクセス トークンを生成し、API リクエストを認証します。アクセス トークンは、OAuth 2.0 仕様に従って 1 時間（3600 秒）のみ有効です。アクセス トークンの有効期限が切れると、漏洩したアクセス トークンを時間制限なく使用できるようなリプレイ攻撃を防ぐことができます。 | Atlas は、ナンスと呼ばれる一意の値を使用して公開キーと秘密キーをハッシュします。ナンスは HTTP ダイジェスト認証仕様に従って、短期間のみ有効です。これはリプレイ攻撃を防ぐためのもので、ナンスをキャッシュして永久に使用することはできません。 |
Atlas のロールは、サービスアカウントがアクセス トークンを使用して実行できる操作を制限します。アクセス トークンがエラーなしで API エンドポイントを呼び出せるように、ユーザーの場合と同様にサービスアカウントにロールを付与する必要があります。 | Atlas ロールは、API キーが実行できる操作を制限します。API キーで、エラーなく API エンドポイントを呼び出せるようにするには、ユーザーの場合と同様に API キーにロールを付与する必要があります。 |
Atlas は多くのリソースをプロジェクトにバインドします。多くのAPIリソースURLは | Atlas は多くのリソースをプロジェクトにバインドします。多くのAPIリソースURLは |
各サービスアカウントは 1 つの組織のみに属しますが、その組織内の任意の数のプロジェクトへのアクセスをサービスアカウントに許可できます。 | 各 API キーは 1 つの組織のみに属しますが、その組織内の任意の数のプロジェクトに API キーによるアクセスを許可できます。 |
サービスアカウントまたはそのアクセス トークンを使用して、Atlas UI から Atlas にログインすることはできません。 | API キーを使用して Atlas UI 経由で Atlas にログインすることはできません。 |
オプション: Atlas Administration API の IP アクセス リストを要求する
Atlas UI を使用して組織を作成すると、Atlas ではデフォルトで、API IP アクセス リスト機能が有効になります。これにより、API リクエストは、IP アクセス リストで指定したロケーション ベースの IP または CIDR アドレスからのものに限定されます。Atlas Administration API に IP アクセス リスト エントリなしでリクエストを行うと、サーバーは 403 ステータスコードで応答します。
この機能を無効にすると、IP アクセスリストが空である限り、インターネット上の任意のアドレスから API リクエストを行うことができます。IP アクセス リスト エントリを追加すると、その IP アドレスからのリクエストのみが許可されます。
組織の作成後、すべての Atlas Administration API リクエストに対して IP アクセス リストを要求するように組織を設定するには、次の手順を実行します。
Atlas で、 Organization Settings ページに移動します。
警告
ナビゲーションの改善が進行中
現在、新しく改善されたナビゲーション エクスペリエンスを展開しています。次の手順が Atlas UIのビューと一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
[Organizations] メニューの横にある [Organization Settings] アイコンをクリックします。
[ Organization Settings ]ページが表示されます。
組織へのプログラムによるアクセスの付与
サービス アカウントまたはAPIキーを使用して、組織へのプログラムによるアクセスを許可するには、次の手順に従います。これら 2 つの認証方法の詳細については、「 Atlas Administration API認証 」を参照してください。
必要なアクセス権
次のアクションを実行するには、Atlas に対する Organization Owner アクセス権が必要です。
Atlas で、Organization Access Manager ページに移動します。
警告
ナビゲーションの改善が進行中
現在、新しく改善されたナビゲーション エクスペリエンスを展開しています。次の手順が Atlas UIのビューと一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーの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 キーの作成
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 ページに移動します。
警告
ナビゲーションの改善が進行中
現在、新しく改善されたナビゲーション エクスペリエンスを展開しています。次の手順が Atlas UIのビューと一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからOrganization Accessを選択します。
サイドバーの Access Manager をクリックします。
[ Organization Access Manager ]ページが表示されます。
API Key Information を入力します。
Descriptionと入力します。
Organization Permissions メニューで、API キーの新しいロールを選択します。
プロジェクトへのプログラムによるアクセスの付与
サービス アカウントまたはAPIキーを使用して、プロジェクトへのプログラムによるアクセスを許可するには、次の手順に従います。これら 2 つの認証方法の詳細については、「 Atlas Administration API認証 」を参照してください。
必要なアクセス権
サービスアカウントにプロジェクトへのアクセス権を付与するには、そのプロジェクトを所有する組織への Organization Owner アクセス権が必要です。
API キーにプロジェクトへのアクセス権を付与するには、そのプロジェクトに対する Project Owner アクセス権が必要です。
プロジェクトへの既存の組織アクセス権の割り当て
組織のサービス アカウントまたはAPIキーをすでに作成している場合は、それらをプロジェクトに割り当てて、そのプロジェクトに Atlas Administration APIへのアクセスを許可できます。
警告
組織サービスアカウントをプロジェクトに割り当てると、Project Owner はシークレットのローテーションや IP アクセス リストの更新などを含め、サービスアカウントを管理できます。
Atlas で、Project Access Manager ページに移動します。
警告
ナビゲーションの改善が進行中
現在、新しく改善されたナビゲーション エクスペリエンスを展開しています。次の手順が Atlas UIのビューと一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
プロジェクト ロールをサービスアカウントに割り当てます。
表示されるメニューで、サービスアカウントの新しいロールを選択します。
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 ページに移動します。
警告
ナビゲーションの改善が進行中
現在、新しく改善されたナビゲーション エクスペリエンスを展開しています。次の手順が Atlas UIのビューと一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
API キーをプロジェクトに追加します。
フィールドに公開キーを入力します。
Project Permissions メニューで、API キーの新しいロールを選択します。
プロジェクトからのプロジェクト アクセス権の追加
組織のサービス アカウントやAPIキーをまだ作成していないAPIは、プロジェクト用にそれらを作成して、Atlas Administration プロジェクトへのアクセスを許可します。プロジェクトに対して作成したサービス アカウントまたはAPIキーは、権限Organization Member を持つ親組織に自動的に追加されます。
Atlas UI を使用してプロジェクトのサービスアカウントを作成する場合
Atlas で、Project Access Manager ページに移動します。
警告
ナビゲーションの改善が進行中
現在、新しく改善されたナビゲーション エクスペリエンスを展開しています。次の手順が Atlas UIのビューと一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーの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}" } ] }%
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 ページに移動します。
警告
ナビゲーションの改善が進行中
現在、新しく改善されたナビゲーション エクスペリエンスを展開しています。次の手順が Atlas UIのビューと一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
まだ表示されていない場合は、ナビゲーション バーのProjectsメニューから目的のプロジェクトを選択します。
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからProject Accessを選択します。
Projectsメニューの横にある次を展開します[ Options ] メニューで [] をクリックし、サイドバーの [ Access Manager Project Settingsをクリックします。
プロジェクト アクセス マネージャーページが表示されます。
API Key Information を入力します。
[Create API Key] ページで次を行います。
Descriptionと入力します。
Project Permissions メニューで、API キーの新しいロールを選択します。
API リクエストを行う
Atlas Administration API、リクエストを認証するために、サービス アカウントまたはAPIキーの 2 つの認証方法のいずれかを使用します。次の手順を完了するには、希望する認証方法を構成するときに保存したキーまたはシークレットが必要です。
すべての Atlas Administration API エンドポイントには次のベース URL があります。
https://cloud.mongodb.com/api/atlas/<version>
サービスアカウントを使用して 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" }'
リクエストは次の例のようになります。ここで、{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" }'
以下も参照してください。
あるいは、OpenAPI v3 仕様 をサポートする任意のツールを使用して、コードサンプルやモック サーバーを生成することもできます。たとえば、Atlas Admin API 仕様をPostman にインポートして curl コマンドを生成できます。Postman を使用して curl コマンドを生成するには、次のようにします。
MongoDB Atlas Administration API ドキュメント で、[Download（ダウンロード）] ボタンを右クリックしてリンクをコピーします。
サービス アカウント シークレットのローテーション
サービス アカウントのシークレットは、作成時に指定された期間（8 時間から 365 日）の経過後に期限切れになります。シークレットをローテーションする段階になると、Atlas はアラートService Account Secrets are about to expire を返します。
注意
サービス アカウント アラートを構成するには、「 アラート設定の構成 」を参照してください。
サービス アカウント シークレットをローテーションするには、次の手順を実行して新しいクライアントシークレットを生成し、新しいクライアントシークレットでアプリケーションを更新して、古いシークレットを削除します。
Atlas UIを使用して、新しいクライアントシークレットを生成し、古いクライアントシークレットを削除できます。
Atlas で、Organization Access Manager ページに移動します。
警告
ナビゲーションの改善が進行中
現在、新しく改善されたナビゲーション エクスペリエンスを展開しています。次の手順が Atlas UIのビューと一致しない場合は、プレビュー ドキュメントを参照してください。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
次のいずれかの手順を行います。
ナビゲーション バーのAccess ManagerメニューからOrganization Accessを選択します。
サイドバーの Access Manager をクリックします。
[ Organization Access Manager ]ページが表示されます。
新しいクライアントシークレットを使用してアプリケーションを更新します。
重要
新しいクライアントシークレットを生成すると、古いクライアントシークレットは 7 日以内に期限切れになります。この有効期限は、古いシークレットの元の有効期限によっては、短縮される可能性があります。
古いシークレットが新しいシークレットの作成後に 7 日以上経過するように設定されている場合、その有効期限は新しいシークレットの作成日から 7 日に短縮されます。
古いシークレットが新しいシークレットの作成日から 7 日未満で期限切れになるように設定されている場合は、元の有効期限が維持されます。
Atlas Administration APIへのアクセスを失うのを避けるため、可能な限りすぐに新しいクライアントシークレットを使用してアプリケーションを更新してください。
Atlas Administration APIを使用して、次のことが可能です。
重要
新しいクライアントシークレットを生成すると、古いクライアントシークレットは 7 日以内に期限切れになります。この有効期限は、古いシークレットの元の有効期限によっては、短縮される可能性があります。
古いシークレットが新しいシークレットの作成後に 7 日以上経過するように設定されている場合、その有効期限は新しいシークレットの作成日から 7 日に短縮されます。
古いシークレットが新しいシークレットの作成日から 7 日未満で期限切れになるように設定されている場合は、元の有効期限が維持されます。
Atlas Administration APIへのアクセスを失うのを避けるため、可能な限りすぐに新しいクライアントシークレットを使用してアプリケーションを更新してください。
次のステップ
Atlas Administration API の詳細については、「Atlas Administration API リファレンス」を参照してください。
プログラムによる Atlas Administration API へのアクセスを管理するには、次のいずれかの手順を参照してください。