重要
それぞれの Atlas Administration API には独自のリソースがあり、初期設定が必要です。
Atlas Administration API サーバーには、パブリック インターネット経由でのみアクセスできます。ネットワーク ピアリングやプライベートエンドポイントを使用した接続では Atlas Administration API を利用できません。
詳細については、 「プログラムによる Atlas へのアクセス」を参照してください。
Atlas Administration API は、 REST アーキテクチャ スタイルの原則に従い、Atlas の管理機能へのプログラムによるアクセスを可能にする多数の内部リソースを公開します。 Atlas Administration APIの詳細については、「 Atlas Administration APIリファレンス 」を参照してください。
Atlas Administration API、クラスターに保存されているデータへのアクセスは提供されていません。データベースでデータを読み取りまたは書き込みするには、適切な読み取りまたは書込みロールを持つ データベースユーザーの認証情報を使用してクラスターで認証する必要があります。 Atlas Administration API を使用して、データベースユーザーを作成および管理できます。
Atlas Administration API を使用して Atlas クラスターを管理するには、次のいずれかの認証方法でAPIリクエストを認証する必要があります。
サービス アカウント アクセス トークン（ OAuth2.0 ）
APIキー（ HTTPダイジェスト認証）
これらの方法の詳細については、「 Atlas Administration API認証メソッド 」を参照してください。
次のセクションでは、サービス アカウントとAPIキーを使用して、Atlas 組織とプロジェクトへのプログラムによるアクセスを構成する方法について説明します。
必要なアクセス権
組織のサービス アカウントまたはAPIキーを作成するには、その組織へのOrganization Owner アクセス権が必要です。
プロジェクトへのサービス アカウントへのアクセスを許可するには、プロジェクト を所有する組織へのOrganization Owner アクセス権が必要です。
プロジェクトへのAPIキー Project Ownerアクセスを許可するには、そのプロジェクトに対する アクセス権が必要です。
オプション: 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 ページに移動します。
まだ表示されていない場合は、以下から目的の組織を選択しますナビゲーション バーのOrganizationsメニュー
サイドバーで、Organization Settings をクリックします。
[ Organization Settings ]ページが表示されます。
Atlas へのプログラムによるアクセスの付与
次の 2 つの認証方法のいずれかを使用して、組織またはプロジェクトへのプログラムによるアクセスを許可できます。
重要
Atlas Administration APIで認証するには、 APIキーではなくサービス アカウントを使用することをお勧めします。 APIキーは、レガシー認証方法です。
サービスアカウント（推奨） | APIキー（レガシー） |
|---|---|
業界標準の OAuth 2.0 プロトコルとクライアント認証情報フローを使用して Atlas に認証する新しい方法。 | HTTPダイジェスト認証を使用する Atlas へのレガシー認証方法。 |
サービスアカウントを作成したら、そのクライアント ID とシークレットを使用してアクセス トークンを生成し、API リクエストを認証します。アクセス トークンは、OAuth 2.0 仕様に従って 1 時間（3600 秒）のみ有効です。アクセス トークンの有効期限が切れると、漏洩したアクセス トークンを時間制限なく使用できるようなリプレイ攻撃を防ぐことができます。 | Atlas は、ナンスと呼ばれる一意の値を使用して公開キーと秘密キーをハッシュします。ナンスは HTTP ダイジェスト認証仕様に従って、短期間のみ有効です。これはリプレイ攻撃を防ぐためのもので、ナンスをキャッシュして永久に使用することはできません。 |
Atlas ロールは、サービス アカウントがアクセス トークンを使用して実行できる操作を制限します。サービス アカウントがAPI呼び出しに必要な権限で必要なアクセス トークンを生成するようにするには、ユーザーの場合と同様にサービス アカウントにロールを割り当てる必要があります。 | |
各サービス アカウントは 1 つの組織にのみ属し、その組織内の任意の数のプロジェクトへのアクセスを許可できます。組織レベルのサービス アカウントにプロジェクトへのアクセス権を付与するには、「 プロジェクトへの既存のサービス アカウントのアクセス権の付与 」を参照してください。 | APIキーの各ペアは 1 つの組織にのみ属し、その組織内の任意の数のプロジェクトへのアクセスを許可できます。プロジェクトへの組織レベルのAPIキー アクセスを付与するには、「 プロジェクトへの既存のサービス アカウント アクセスの付与 」を参照してください。 |
サービス アカウントまたはそのアクセス トークンを使用して、 Atlas UIから Atlas にログことはできません。サービス アカウントでは Atlas Administration APIへのアクセスのみが許可されます。これにはUIアクセスやクラスター データへのアクセスは含まれません。 | APIキーを使用して Atlas UIから Atlas にログことはできません。 APIキーは Atlas Administration APIへのアクセスのみを許可します。これには、 UIアクセスやクラスター データへのアクセスは含まれません。 |
組織へのプログラムによるアクセスの付与
サービス アカウントまたはAPIキーを使用して、組織へのプログラムによるアクセスを許可するには、次の手順に従います。これら 2 つの認証方法の詳細については、「 Atlas Administration API認証メソッド 」を参照してください。
プロジェクトへのプログラムによるアクセスの付与
サービス アカウントまたはAPIキーを使用して、プロジェクトへのプログラムによるアクセスを許可するには、次の手順に従います。これら 2 つの認証方法の詳細については、「 Atlas Administration API認証メソッド 」を参照してください。
プロジェクトからのプロジェクト アクセス権の追加
組織用のサービス アカウントまたは API キーをまだ作成していない場合は、プロジェクト用に作成して、そのプロジェクトに Atlas Administration API へのアクセス権を付与できます。プロジェクト用に作成したサービス アカウントまたは API キーは、Organization Member 権限を持つ親組織に自動的に追加されます。
API リクエストを行う
Atlas Administration API は、サービス アカウントまたは API キーという 2 つの認証方法のいずれかを使用してリクエストを認証します。次の手順を完了するには、希望する認証方法を構成するときに保存したキーまたはシークレットが必要です。
すべての Atlas Administration API エンドポイントには次のベース URL があります。
https://cloud.mongodb.com/api/atlas/<version>
重要
MongoDB は、セキュリティを強化するために HTTPS URL を使用します。HTTP URL を使用すると、301ステータスコードが返されます。
あるいは、OpenAPI v3 仕様 をサポートする任意のツールを使用して、コードサンプルやモック サーバーを生成することもできます。たとえば、Atlas Admin API 仕様をPostman にインポートして curl コマンドを生成できます。
警告
Postman を使用して HTTP URL を使用すると、期待どおりに301ステータスコードが返されます。しかし、このシナリオでは、Postman が HTTPS でリクエストを自動的に再試行する可能性がありますが、同時に再試行リクエストからヘッダーと本文を削除することがあります。これにより、301ではなく401のステータスコードが返され、リクエストが失敗した理由を特定することが困難になります。
以下の方法で、Postman を使用して curl コマンドを生成します。
MongoDB Atlas Administration API ドキュメント で、[Download（ダウンロード）] ボタンを右クリックしてリンクをコピーします。
次のステップ
Atlas Administration API の詳細については、「Atlas Administration API リファレンス」を参照してください。
プログラムによる Atlas Administration API へのアクセスを管理するには、次のいずれかの手順を参照してください。