action.skip

API キーの作成

Megaport API コールには、API キーを作成した後に生成するアクセス トークンが必要です。アクセス トークンは API ユーザーの認証に必要で、Megaport Portal の必要な部分だけに一時的にアクセスできるようにするものです。

Megaport API にアクセスし、API キーを作成するために、マシン ツー マシン (M2M) 会社管理者アカウントを作成することを推奨します。人間のユーザーがアカウントを停止またはロックアウトされた場合、そのユーザーによって作成された API キーも停止され、 API 統合が機能しなくなる可能性があります。

API キーは、それらが生成された環境でのみ有効です。別の環境にアクセスするために API キーが必要な場合は、その環境で Megaport Portal にログインし、そこで API キーを生成します

注意

  • API キーを作成するには、会社管理者ロールを持つユーザーとして Megaport Portal にログインする必要があります。詳細については、ユーザーロールの管理を参照してください。

  • API キーは 1 社につき最大 5 つまで作成できます。

このトピックでは、次のタスクについて説明します。

  • Megaport Portal で API キーを作成する
  • Postman でアクセス トークンを生成する

Megaport Portal で API キーを作成する

  1. Megaport Portal で、「Tool (ツール)」 > 「API Key Generator (API キー ジェネレータ)」を選択します。
    「API Keys (API キー)」ページでは、API キーの作成、および既存の API キーの表示と編集を行うことができます。
    API キー画面
  2. API キーの詳細を指定します。

    • Name (名前) – API キーの名前を入力します。
      これは、キーの目的を識別する記述的な名前でなければなりません。

      注意

      • API キーの名前には最低 3 文字が必要です。

      • ダッシュとハイフンを除き、特殊文字は使用できません。

    • ロール – API を使用するユーザーのロールを選択します。
      次のオプションが利用可能です。

      • 会社管理者
      • 読み取り専用
    • Token Expiry (Minutes) (トークンの有効期限 (分)) – このキーから生成されたトークンが失効するまでの時間を分単位で入力します。最小値は 5 分、最大値は 24 時間 (1440 分) です。トークンが失効したら、新規アクセス トークンを生成する必要があります。

  3. Generate Key (キーの生成)」をクリックします。
    API キーが作成され、「Your API Key (お客様の API キー)」プロンプトが表示されます。
    お客様の API キー プロンプト

    重要

    新規 API キーと API キー シークレットをコピーし、それらの資格情報を安全な場所に保管します。これらの情報はアクセス トークンを生成する際に使用する必要があります。このプロンプトを閉じると、API キー シークレットは再表示されないので、必ずコピーしてください。

  4. API キー フィールドの右側にある「Copy (コピー)」をクリックし、キー (クライアント ID) を安全な場所に貼り付けます。

  5. API キー シークレット フィールドの右側にある「Copy (コピー)」をクリックし、クライアント シークレットを安全な場所に貼り付けます。

  6. Close(閉じる)」をクリックします。
    API キーが作成され、画面の「Active API Keys (アクティブな API キー)」エリアに表示されます。
    「Active API Keys (アクティブな API キー)」エリアでは、キー名の編集、キーの削除、キーに行った変更の履歴を表示することができます。

アクセス トークンの生成

クライアント ID とクライアント シークレットから構成される API キーを作成したら、API ユーザーを認証するためのアクセス トークンを生成することができます。ここでは、Postman と Megaport コレクションを使ってこれを行う方法について説明します。Postman 設定の詳細については、Megaport API を参照してください。

アクセス トークンを生成する環境に応じて、使用する必要のあるリクエスト URL は異なります。各環境で、以下のリクエスト URL を使用する必要があります。

  • 本番環境:- https://auth-m2m.megaport.com/oauth2/token
  • ステージング (テスト) 環境:- https://oauth-m2m-staging.auth.ap-southeast-2.amazoncognito.com/oauth2/token

ここでは、本番環境でアクセス トークンを生成する方法について説明します。 詳細については、Megaport API を参照してください。

注意

アクセス トークンがどの API エンドポイントを呼び出せるかは、API キー作成時に選択されたロールによって異なります例えば、読み取り専用の API キーは、会社管理者の API キーよりもアクセス可能なデータに制限があります。

Postman でアクセス トークンを生成するには

  1. Postman でインポートした Megaport コレクションで、プラス アイコンをクリックして、新しいリクエストを追加します。
    新規リクエストの追加
  2. リクエスト URL フィールドの左側にあるドロップダウン リストで、「POST」を選択します。
    POST エンドポイント タイプの選択
  3. リクエスト URL フィールドに、次のリクエスト URL を入力します。
    https://auth-m2m.megaport.com/oauth2/token
    リクエスト URL
  4. 「Authorization (承認)」タブを選択して、以下のパラメーターの詳細を入力します。
    • Username (ユーザー名) – API キー作成時にコピーしたクライアント ID です。
    • Password (パスワード) – API キー作成時にコピーしたクライアント シークレットです。

    注意

    これらのパラメーターには機密データが含まれています。コラボレーション環境で作業している場合は、クライアント ID とクライアント シークレットを変数 {{apiKeyClientId}} と {{apiKeyClientSecret}} にそれぞれ設定するとよいでしょう。変数の詳細については、Postman のドキュメンテーションを参照してください。

    アクセス トークン エンドポイント承認パラメーター

  5. 「Body (本文) 」タブをクリックし、client_credentials の値に設定されている grant_type というキーを入力します。
    アクセス トークン エンドポイント本文パラメーター
  6. Save(保存)」をクリックします。
    「Save Request (リクエストの保存)」画面が表示されます。
    「Save Request (リクエストの保存)」画面
  7. 「Request name (リクエスト名)」フィールドには、新規リクエストのわかりやすい名前を入力します。
    例えば、「Generate Access Token」などです。
  8. (オプション) リクエストの説明を入力します。
  9. リクエストを保存する場所を選択し、「Save (保存)」をクリックします。
    新規リクエストが作成され、Megaport API ドキュメンテーション コレクションに追加されます。
  10. 「Send(送信)」をクリックします。
    アクセス トークンのリクエストを送信する
    次の例のように、アクセス トークンを含む応答が返ってくるはずです。アクセス トークンが生成されると、Megaport Portal のさまざまなエンドポイントで API ユーザーの認証に使用できます。

     {
      "access_token":  
          "eyJraWQ......2cOQGA",
      "expires_in": 86400,
      "token_type": "Bearer"
     }
    
  11. アクセス トークンをコピーします。

  12. コレクションの変数 (インポートされた Megaport コレクション> Edit (編集) > Variables (変数) の後にある 3 つのドットをクリックします) で、access_token のエントリを追加し、アクセス トークンを「CURRENT VALUE (現在の値)」フィールドに貼り付けます。
  13. 送信する必要のある API コールごとに、「Authorization (承認)」タブで「Type (タイプ)」を Bearer トークンに設定し、「Token (トークン)」をアクセス トークン変数に設定する必要があります{{access_token}}。
    API のアクセス トークンを設定する
    これで、API コールを使用する準備が整いました。 すべての API コールは SSL/TLS を介して行われ、すべてのコールをアクセス トークンと照合し、適切な権限があるかどうかを検証します。

注意

アクセス トークンは失効するため、定期的にAPI コール用の新規トークンを生成する必要があります。有効期限は、API キーの作成時に「Token Expiry (Minutes) (トークンの有効期限 (分))」フィールドに入力した値によって決まります。デフォルトの有効期限は 24 時間です。

API リクエストには 2 つの重要なヘッダー パラメーターが含まれています。Authorization (承認) と Content - Type (コンテンツ - タイプ) です。Authorization パラメーターは、トークン変数が設定されている「Authorization (承認) 」タブを指します。

必要なヘッダー

cURL トークン生成

アクセス トークンを生成する別の方法は、コマンド コンソールから次の形式で cURL を使用することです。

 curl -X "POST" "https://auth-m2m.megaport.com/oauth2/token" \
        -H 'Content-Type: application/x-www-form-urlencoded' \
        -u 'value_of_base64(clientId:clientSecret)_here' \
        --data-urlencode "grant_type=client_credentials"

ヒント

dev.megaport.com サイトでは、各 API エンドポイントを複数のプログラミング言語で表示できます。