デプロイメント管理API

このページでは、Platform APIを使用してデプロイメントの一覧取得、デプロイメントの詳細および接続情報の取得、デプロイメントの開始・停止、デプロイメントの作成、およびデプロイメントAPIキーの作成方法について説明します。

デプロイメント一覧取得

URI

GET /deployments

TIP

このメソッドは60分間に60回までしかリクエストできません。

リクエストメッセージ

なし

レスポンスメッセージ

200:

名前	型	説明
connections	Number	デプロイメントの接続数。
tps	Number	デプロイメントの1秒あたりのトランザクション数（TPS）。
createAt	String	デプロイメントの作成日時。
deploymentID	String	一意のデプロイメントID。
deploymentName	String	デプロイメント名。
deploymentType	String	デプロイメントのタイプ："serverless"はサーバレス版、"dedicated"は専用版、"dedicatedFlex"は専用Flex版。
platform	String	デプロイメントのクラウドサービスプロバイダー。
projectName	String	デプロイメントに紐づくプロジェクト名。
region	String	デプロイメントが配置されているリージョン。
status	String	デプロイメントの現在の状態："running"、"starting"、"stopped"のいずれか。
version	String	デプロイメントのバージョン。

401: APIキーの認証に失敗しました。
403: APIキーにリクエストされたリソースへのアクセス権限がありません。
429: リクエスト制限を超えました。

リクエスト例

bash

curl -u key:secret -X GET {api}/deployments

レスポンス例

json

[
    {
        "connections": 1000,
        "tps": 1000,
        "createAt": "2024-11-21 02:51",
        "deploymentID": "mdfba81f",
        "deploymentName": "deployment-mdfba81f",
        "deploymentType": "serverless",
        "platform": "AWS",
        "projectName": "default",
        "region": "N. Virginia (us-east-1)",
        "status": "stopped",
        "version": "v5"
    },
    {
        "connections": 1000,
        "tps": 1000,
        "createAt": "2025-04-17 08:36",
        "deploymentID": "b1f77113",
        "deploymentName": "deployment-b1f77113",
        "deploymentType": "dedicatedFlex",
        "platform": "AWS",
        "projectName": "test",
        "region": "N. Virginia (us-east-1)",
        "status": "running",
        "version": "v5"
    }
]

デプロイメント詳細および接続情報の取得

URI

GET /deployments/{deployment_id}

TIP

このメソッドは60分間に60回までしかリクエストできません。{deployment_id}はデプロイメント名ではなく、デプロイメントIDを指します。

リクエストメッセージ

なし

レスポンスメッセージ

200:

名前	型	説明
connections	Number	デプロイメントの接続数。
tps	Number	デプロイメントの1秒あたりのトランザクション数（TPS）。
createAt	String	デプロイメントの作成日時。
deploymentID	String	一意のデプロイメントID。
deploymentName	String	デプロイメント名。
deploymentType	String	デプロイメントのタイプ。"dedicated"は専用版、"dedicatedFlex"は専用Flex版。
platform	String	デプロイメントのクラウドサービスプロバイダー。
region	String	デプロイメントが配置されているリージョン。
status	String	デプロイメントの現在の状態："running"、"starting"、"stopped"のいずれか。
connection	Objectまたはnull	デプロイメントの接続情報。稼働中のデプロイメントの場合、このオブジェクトには接続アドレス、利用可能な全ポートとその状態、およびAPIエンドポイントが含まれます。稼働していない場合は`null`。

401: APIキーの認証に失敗しました。
403: APIキーにリクエストされたリソースへのアクセス権限がありません。
404: デプロイメントが見つかりません。
429: リクエスト制限を超えました。

リクエスト例

bash

curl -u key:secret -X GET {api}/deployments/w41b11c0

レスポンス例

json

{
    "connections": 1000,
    "tps": 1000,
    "createAt": "2024-07-22 05:32",
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "deploymentType": "dedicated",
    "platform": "AWS",
    "region": "N. Virginia (us-east-1)",
    "status": "running",
    "connection": {
        "address": "mqtt.example.com",
        "ports": [
            {"protocol": "mqtt", "port": 1883, "status": "running"},
            {"protocol": "mqtts", "port": 8883, "status": "running"},
            {"protocol": "ws", "port": 8083, "status": "running"},
            {"protocol": "wss", "port": 8084, "status": "running"}
        ],
        "apiEndpoint": "https://mqtt.example.com:8443/api/v5"
    }
}

上記のアドレスとポートは例です。実際にはデプロイメントから返される値を使用し、statusがrunningのポートにのみ接続してください。

稼働していないデプロイメントの場合、レスポンスには"connection": nullが含まれます：

json

{
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "status": "stopped",
    "connection": null
}

デプロイメントAPIキーの作成

Platform APIキーを使用して、稼働中のDedicatedまたはDedicated Flexデプロイメント用のデプロイメントAPIキーを作成します。この操作はサーバレスデプロイメントおよび稼働していないデプロイメントでは利用できません。

Platform APIキーはDeployment_API_Key権限を持ち、対象プロジェクトへのアクセス権が必要です。対象デプロイメントはPlatform APIキーに紐づくアカウントに属している必要があります。デプロイメントあたり最大5つのデプロイメントAPIキーを作成可能です。各Platform APIキーは1時間あたり2回までデプロイメントAPIキーの作成に成功できます。

URI

POST /deployments/{deployment_id}/applications

{deployment_id}はデプロイメント名ではなくデプロイメントIDです。

リクエストメッセージ

リクエストボディは任意です。ボディを指定する場合はapplication/jsonを使用し、whitelistフィールドを含めます。

名前	型	必須	説明
`whitelist`	Object	ボディ提供時必須	デプロイメントAPIの権限を、APIパスをキー、許可するHTTPメソッドの配列を値とするマッピングで表現します。指定されたHTTPメソッドは、対応するAPIパスでデプロイメントがサポートしている必要があります。
`description`	Stringまたはnull	任意	キーの説明。最大128文字。省略時は空文字列となります。

例として、"/api/v5/clients": ["GET"]はクライアント一覧取得のみ許可します。同じwhitelist内で異なるパスに異なるメソッドを指定可能です。指定されていない権限は新しいキーに付与されません。デプロイメントで利用可能な権限の中から必要なものだけを付与してください。

重要

リクエストボディを省略すると、新しいキーにはデプロイメントで利用可能なすべてのAPI権限が付与されます。空のJSONオブジェクト{}は省略とは異なり拒否されます。無効なwhitelistや不正なContent-Typeのリクエストもキー作成なしで拒否されます。

レスポンスメッセージ

201: 作成成功。

名前	型	説明
`appID`	String	新規デプロイメントAPIキーのApp ID（AK）。
`appSecret`	String	新規デプロイメントAPIキーのApp Secret（SK）。作成時のみ返されます。

400: デプロイメントタイプまたは状態が操作をサポートしていない、要求された権限が利用不可、またはキー上限に達している。
401: Platform APIキーの認証に失敗しました。
403: Platform APIキーにDeployment_API_Key権限または対象プロジェクトへのアクセス権がありません。
404: デプロイメントが見つかりません。
415: リクエストボディのメディアタイプがサポートされていません。
422: リクエストパラメータまたはボディが不正です。
429: リクエスト制限を超えました。

リクエスト例

この例では、クライアント一覧取得と組み込みデータベースのユーザー一覧取得および作成を許可するキーを作成します。コマンド実行前に、Platform APIエンドポイント、Platform APIキーの認証情報、対象デプロイメントIDを環境変数に設定してください。

bash

curl --user "$PLATFORM_API_KEY:$PLATFORM_API_SECRET" \
  -X POST "$PLATFORM_API_ENDPOINT/deployments/$DEPLOYMENT_ID/applications" \
  -H "Content-Type: application/json" \
  -d '{
    "whitelist": {
      "/api/v5/clients": ["GET"],
      "/api/v5/authentication/password_based:built_in_database/users": ["GET", "POST"]
    },
    "description": "Application API access"
  }'

PLATFORM_API_ENDPOINTは/public_api/v1で終わるPlatform APIエンドポイントに設定してください。例の/api/v5/パスは対象デプロイメントでサポートされている場合のみ利用可能です。利用可能なパスとメソッドはデプロイメントによって異なります。

レスポンス例

json

{
  "appID": "example-app-id",
  "appSecret": "example-app-secret"
}

appSecretは作成時にのみ返されるため、安全に保管してください。新しいキーはコンソールに表示され、監査ログには秘密情報は記録されません。デプロイメントAPIを呼び出す際は、デプロイメント詳細のconnection.apiEndpointを使用し、HTTP Basic認証でappIDとappSecretを用いて認証してください。Platform APIキーを使ってデプロイメントAPIを呼び出さないでください。

デプロイメント停止

URI

POST /deployments/{deployment_id}/stop

TIP

このメソッドは60分間に5回までしかリクエストできません。{deployment_id}はデプロイメント名ではなくデプロイメントIDを指します。この操作は専用デプロイメントのみ利用可能です。

リクエストメッセージ

なし

レスポンスメッセージ

201:

名前	型	説明
deploymentID	String	一意のデプロイメントID。
deploymentName	String	デプロイメント名。
operation	String	操作種別。"stopping"は停止操作を示します。

401: APIキーの認証に失敗しました。
403: APIキーにリクエストされたリソースへのアクセス権限がありません。
404: デプロイメントが見つかりません。
422: リクエストパラメータが不正です。
429: リクエスト制限を超えました。

リクエスト例

bash

curl -u key:secret -X POST {api}/deployments/w41b11c0/stop

レスポンス例

json

{
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "operation": "stopping"
}

デプロイメント開始

URI

POST /deployments/{deployment_id}/start

TIP

リクエストメッセージ

なし

レスポンスメッセージ

201:

名前	型	説明
deploymentID	String	一意のデプロイメントID。
deploymentName	String	デプロイメント名。
operation	String	操作種別。"starting"は開始操作を示します。

401: APIキーの認証に失敗しました。
403: APIキーにリクエストされたリソースへのアクセス権限がありません。
404: デプロイメントが見つかりません。
422: リクエストパラメータが不正です。
429: リクエスト制限を超えました。

リクエスト例

bash

curl -u key:secret -X POST {api}/deployments/w41b11c0/start

レスポンス例

json

{
    "deploymentID": "w41b11c0",
    "deploymentName": "deployment-w41b11c0",
    "operation": "starting"
}

デプロイメント作成

URI

POST /deployments

TIP

各Platform APIキーは1時間あたり最大2つのデプロイメントを正常に作成できます。デプロイメントはデフォルトプロジェクトに作成され、時間単位で課金されます。EMQX v5およびv6のデプロイメントがサポートされています。

リクエストメッセージ

名前	型	必須	説明
platform	String	はい	デプロイメントをホストするクラウドプラットフォーム。
region	String	はい	デプロイメントを作成するリージョン。
connections	Number	はい	デプロイメントの接続数。サーバレスデプロイメントは1,000接続、専用デプロイメントは1,000～10,000接続をサポート。
tps	Number	はい	デプロイメントの1秒あたりのトランザクション数（TPS）。
deploymentType	String	はい	デプロイメントプラン。"serverless"または"dedicatedFlex"のいずれか。
deploymentName	String	いいえ	デプロイメント名。省略するとシステムがデフォルト名を生成。
deploymentVersion	String	はい	デプロイメントのバージョン。"v5"または"v6"がサポートされています。
projectID	String	はい	プロジェクトID。プロジェクト一覧から取得可能。
freeTrial	Boolean	はい	デプロイメントが無料トライアルかどうか。`false`に設定する必要があります。

対応プランのクラウドプロバイダーおよびリージョンについてはCloud Providers and Regionsを参照してください。

異なるデプロイメントエディションは異なる接続数およびTPS仕様をサポートします。

接続数	TPS
1,000	1,000

接続数	TPS
1,000	1,000
2,000	2,000
5,000	10,000
10,000	20,000

レスポンスメッセージ

201:

名前	型	説明
createAt	String	デプロイメントの作成日時。
deploymentID	String	一意のデプロイメントID。
deploymentName	String	デプロイメント名。
deploymentType	String	デプロイメントのタイプ（"dedicatedFlex"または"serverless"）。
platform	String	クラウドプラットフォームの識別子。
ports	Object	プロトコル別（MQTT、WebSocketなど）のポート設定。
projectID	String	このデプロイメントが属するプロジェクトのID。
region	String	クラウドリージョンの識別子。
regionLabel	String	リージョンの人間が読みやすい名称。
spec	Object	接続数、バージョンなどを含むデプロイメント仕様。
status	String	デプロイメントの現在の状態（running、stopped、pending）。
subscription	Boolean	このデプロイメントがサブスクリプションベースかどうか。
userID	String	このデプロイメントの所有者ユーザーID。

400: 不正なリクエスト
401: APIキーの認証に失敗しました。
403: APIキーにリクエストされたリソースへのアクセス権限がありません。
422: リクエストパラメータが不正です。
429: Platform APIキーは1時間あたり2回の正常なデプロイメント作成の上限に達しています。

リクエスト例

bash

curl -u key:secret -X POST {api}/deployments \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "aws",
    "region": "us-east-1",
    "connections": 1000,
    "tps": 1000,
    "deploymentType": "dedicatedFlex",
    "deploymentVersion": "v5",
    "projectID": "00000001",
    "freeTrial": false
  }'

レスポンス例

json

{
    "createAt": "2025-04-17 15:30",
    "deploymentID": "i9d0961f",
    "deploymentName": "deployment-i9d0961f",
    "deploymentType": "dedicatedFlex",
    "platform": "aws",
    "ports": {
        "1883": {
            "status": "running",
            "protocol": "mqtt"
        },
        "8083": {
            "status": "running",
            "protocol": "ws"
        },
        "8084": {
            "status": "running",
            "protocol": "wss"
        },
        "8883": {
            "status": "running",
            "protocol": "mqtts"
        }
    },
    "projectID": "00000001",
    "region": "us-east-1",
    "regionLabel": "N. Virginia (us-east-1)",
    "spec": {
        "connections": 1000,
        "deploymentVersion": "v5",
        "freeTraffic": 100,
        "node": 2,
        "protection": false,
        "tps": 1000,
        "version": 5.2
    },
    "status": "pending",
    "subscription": false,
    "tls": null,
    "userID": "00000001"
}

専用フレックス

VPC ピアリング接続

PrivateLinkの設定

拡張認証

拡張認可

アラート

アラートトラブルシューティングガイド

ルール

LLMベースのMQTTデータ処理

サーバレスデプロイAPI

デプロイメント管理API ​

デプロイメント一覧取得 ​

URI ​

リクエストメッセージ ​

レスポンスメッセージ ​

リクエスト例 ​

レスポンス例 ​

デプロイメント詳細および接続情報の取得 ​

URI ​

リクエストメッセージ ​

レスポンスメッセージ ​

リクエスト例 ​

レスポンス例 ​

デプロイメントAPIキーの作成 ​

URI ​

リクエストメッセージ ​

レスポンスメッセージ ​

リクエスト例 ​

レスポンス例 ​

デプロイメント停止 ​

URI ​

リクエストメッセージ ​

レスポンスメッセージ ​

リクエスト例 ​

レスポンス例 ​

デプロイメント開始 ​

URI ​

リクエストメッセージ ​

レスポンスメッセージ ​

リクエスト例 ​

レスポンス例 ​

デプロイメント作成 ​

URI ​

リクエストメッセージ ​

レスポンスメッセージ ​

リクエスト例 ​

レスポンス例 ​

デプロイメント管理API

デプロイメント一覧取得

URI

リクエストメッセージ

レスポンスメッセージ

リクエスト例

レスポンス例

デプロイメント詳細および接続情報の取得

URI

リクエストメッセージ

レスポンスメッセージ

リクエスト例

レスポンス例

デプロイメントAPIキーの作成

URI

リクエストメッセージ

レスポンスメッセージ

リクエスト例

レスポンス例

デプロイメント停止

URI

リクエストメッセージ

レスポンスメッセージ

リクエスト例

レスポンス例

デプロイメント開始

URI

リクエストメッセージ

レスポンスメッセージ

リクエスト例

レスポンス例

デプロイメント作成

URI

リクエストメッセージ

レスポンスメッセージ

リクエスト例

レスポンス例