Yamaha Network Organizer (YNO) の管理APIリファレンスへようこそ。管理APIは、YNOマネージャーを外部システム (Webサービスやお客様ご自身で作成したアプリケーション) から利用するためのREST APIです。管理APIの概要については、YNO操作マニュアルを参照してください。本文書では、管理APIの基本となる利用方法と、サンプルを掲載しています。なお、記載内容は予告なく変更することがあります。あらかじめご了承ください。
HTTPリクエストは以下の形式で送信します。
METHOD BASE_URL/PATH/PATH_PARAMETERS?QUERY_PARAMETERS
HEADER
BODY
各パラメーターには以下を指定してください。
キー名 | 説明 |
---|---|
X-Yamaha-YNO-MngAPI-Key | APIキーを指定してください。 管理APIは、APIキーを利用して認証を行います。APIキーは、YNOマネージャーのGUIで生成できます。生成方法は、YNO操作マニュアルの「APIキーを生成する」を参照してください。 以下の場合、認証エラーになります。
|
X-Yamaha-YNO-MngAPI-Version | 管理APIには、エンドポイント全体で1つのバージョンが付与されています。HTTPクライアントは、リクエスト送信時に管理APIのバージョンを指定します。YNOマネージャーは実際に動作している管理APIのバージョンをレスポンスに含めて返却します。 バージョンは「メジャーバージョン.マイナーバージョン」のフォーマットで管理されます。
HTTPリクエストでバージョンを指定しない場合、最新バージョンで動作します。 |
Content-Type | HTTPメソッドがPOSTまたはPUTの場合、「application/json」を指定してください。 |
ルーターを検索するAPIに送信するリクエストの例を以下に示します。この例では説明を簡略化するため、通常付与されるその他のHTTPヘッダーは省略しています。
POST https://yno-mngapi.netvolante.jp/routers/_search
X-Yamaha-YNO-MngAPI-Key: API_KEY
X-Yamaha-YNO-MngAPI-Version: 1.0
Content-Type: application/json
{}
ルーターを検索するAPIに送信するリクエストについて、言語ごとのサンプルは以下のとおりです。
■curl
curl -X POST \
--header "X-Yamaha-YNO-MngAPI-Key: API_KEY" \
--header "X-Yamaha-YNO-MngAPI-Version: 1.0" \
--header "Content-Type: application/json" \
--data "{}" \
https://yno-mngapi.netvolante.jp/routers/_search
■Python
from urllib import request, error
import json
url = "https://yno-mngapi.netvolante.jp/routers/_search"
headers = {
"X-Yamaha-YNO-MngAPI-Key": "API_KEY",
"X-Yamaha-YNO-MngAPI-Version": "1.0",
"Content-Type": "application/json"
}
body = {}
req = request.Request(
url,
data=json.dumps(body).encode(),
headers=headers,
method="POST"
)
try:
with request.urlopen(req) as res:
print(res.read().decode("utf-8"))
except error.URLError as err:
print(err.read().decode("utf-8"))
■Node.js
var request = require("request");
url = "https://yno-mngapi.netvolante.jp/routers/_search";
headers = {
"X-Yamaha-YNO-MngAPI-Key": "API_KEY",
"X-Yamaha-YNO-MngAPI-Version": "1.0",
"Content-Type": "application/json"
};
body = {};
var options = {
method: "POST",
url: url,
headers: headers,
body: JSON.stringingify(body)
};
request(options, function (error, response) {
if (error) {
throw new Error(error);
}
console.log(response.body);
});
HTTPレスポンスで返却される形式は以下のとおりです。
ステータスコード | リクエストの結果 |
---|---|
2xx | 成功 |
400 | 失敗 (不正なリクエスト) |
401 | 失敗 (APIキーによる認証エラー) |
403 | 失敗 (IPアドレスによる認証エラー) |
404 | 失敗 (リソースが見つからない) |
413 | 失敗 (リクエストボディーのサイズが大きすぎる) |
414 | 失敗 (リクエストURIが長すぎる) |
422 | 失敗 (バリデーションエラー) |
429 | 失敗 (リクエスト制限に達している) |
5xx | 失敗 |
キー名 | 説明 |
---|---|
Content-Type | 「application/json」が返却されます。 |
Retry-After | ステータスコードが「429」の場合に、リクエストが可能になるまでの秒数が返却されます。 |
プロパティ名 | 型 | 説明 | |
---|---|---|---|
Meta | object | ||
MngApiVersion | string | 実際に動作している管理APIのバージョンです。 | |
Data | object | リクエストが「成功」した場合に、この値が追加されます。詳細は、各エンドポイントの仕様を参照してください。 | |
Errors | Array of objects | リクエストが「失敗」した場合に、この値が追加されます。 | |
Code | string | エラーの識別子です。 | |
Message | string | エラーの内容です。 | |
Warnings | Array of objects | リクエストに対して警告がある場合に、この値が追加されます。この値はリクエストの処理結果が成功・失敗いずれの場合にも追加される可能性があります。レスポンスにこの値が含まれる場合、内容を確認し、必要な対応を実施してください。 | |
Code | string | 警告の識別子です。 | |
Message | string | 警告の内容です。 |
以下は、ルーター検索APIへのリクエストに成功した場合に返却されるレスポンスボディーの例です。
{
"Meta": {
"MngApiVersion": "1.0"
},
"Data": {
"Routers": [
{
"DeviceStatus": "Online",
"ModelName": "NVR700W",
"FirmwareRevision": "Rev.15.00.24",
"DeviceDescription": "device05",
"EndpointIpAddress": "192.168.1.1",
"AssignedLabels": [
"浜松本店"
],
"SerialNumber": "M4Y000000",
"AssignedUsers": [
"customer01"
]
}
]
}
}
リクエストに失敗した場合、以下のように失敗した理由が返却されます。一部、理由を返却しないエラーもあります。その場合のボディーは空です。
{
"Meta": {
"MngApiVersion": "1.0"
},
"Errors": [
{
"Code": "INVALID_PROPERTY_TYPE",
"Message": "0 is not of type 'string'."
}
]
}
管理APIのリクエストには、以下の制限があります。
管理APIへのリクエスト結果が「失敗」の場合も、上記の制限に加算されます。制限を超えて管理APIにリクエストした場合、リクエストに失敗し、HTTPレスポンスのステータスコードに「429」が返却されます。
1日あたりの管理APIの使用状況は、YNOマネージャーのGUIの「管理API使用状況」画面で確認できます。
情報を取得するエンドポイントでは、一度に取得できるデータ数に上限があります。すべてのデータを取得するためには、リクエストの送信が繰り返し必要な場合があります。
取得できるデータ数の上限を超えるようなリクエストを送信した場合、以下のデータが返却されます。
NextPageTokenの値を、次のリクエストのPageTokenに指定して送信することで、続きのデータを取得できます。例えば、ルーターを検索するAPIは、以下のような手順で使用します。
NextPageTokenには、5分間の有効期限があります。有効期限が切れてしまった場合、1のリクエストの送信からやりなおす必要があります。
管理しているルーターの情報を取得できます。
Content-Type required | string Value: "application/json" |
X-Yamaha-YNO-MngAPI-Version | string Example: 1.0 管理APIのバージョン 指定しない場合、最新バージョンで動作します。 |
PageSize | integer [ 5 .. 100 ] Default: 20 取得件数 |
object 取得条件 | |
PageToken | string 続きのデータを取得するためのトークン 前回のリクエスト時に返却された「NextPageToken」の値を指定してください。PageTokenを指定した場合、他のパラメーターは無視されます。 |
{- "Query": {
- "Where": {
- "$eq": {
- "SerialNumber": "M5B123456"
}
}
}
}
{- "Meta": {
- "MngApiVersion": "1.0"
}, - "Data": {
- "Routers": [
- {
- "DeviceStatus": "Online",
- "ModelName": "NVR700W",
- "FirmwareRevision": "Rev.15.00.24",
- "DeviceDescription": "device05",
- "EndpointIpAddress": "192.168.1.1",
- "AssignedLabels": [
- "浜松本店"
], - "SerialNumber": "M4Y000000",
- "AssignedUsers": [
- "customer01"
]
}, - {
- "DeviceStatus": "Online",
- "ModelName": " RTX830",
- "FirmwareRevision": "Rev.15.02.30",
- "DeviceDescription": "device01",
- "EndpointIpAddress": "192.168.1.2",
- "AssignedLabels": [
- "浜松本店"
], - "SerialNumber": "M5B000000",
- "AssignedUsers": [
- "customer01"
]
}
]
}
}
タスクを使用することで、機器に特定のアクションを実行できます。
現在、タスクでは以下の機能を利用できます。
タスクは非同期で実行されます。そのため、タスクの登録と実行結果の取得は別々のAPIにリクエストを送信する必要があります。以下の手順でタスクを実行します。
タスクは、登録してから1日経過すると削除されます。
特定のアクションを実行するタスクを登録できます。
Content-Type required | string Value: "application/json" |
X-Yamaha-YNO-MngAPI-Version | string Example: 1.0 管理APIのバージョン 指定しない場合、最新バージョンで動作します。 |
Type required | string Value: "ExecuteCommand" タスクのタイプ
|
Timeout | integer [ 60 .. 1800 ] Default: 900 タスクがタイムアウトになるまでの時間 (単位: 秒) この時間内にタスクが実行されない場合、タスクの実行結果が「TIMEOUT」になります。 |
required | ExecuteCommand (object) タスクの情報 Typeに応じて、指定する内容が異なります。 |
{- "Type": "ExecuteCommand",
- "Parameters": {
- "SerialNumbers": [
- "M4Y000000",
- "S4H000000"
], - "Commands": [
- "show status yno",
- "show environment"
]
}
}
{- "Meta": {
- "MngApiVersion": "1.0"
}, - "Data": {
- "TaskId": 71
}
}
登録されているタスクの実行結果を取得できます。
タスクが実行中の場合、HTTPレスポンスのステータスコード「202」が返却され、実行結果を取得できません。以下のいずれかの状態になると、ステータスコード「200」が返却され、実行結果を取得できます。
タスクの実行結果は、タスクを登録してから1日経過すると削除されます。
TaskId required | integer Example: 10 タスクのID タスクを登録したときに返却される「TaskId」の値を指定してください。 |
PageSize | integer [ 5 .. 100 ] Default: 20 Example: PageSize=50 取得件数 |
PageToken | string Example: PageToken=ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890 続きのデータを取得するためのトークン 前回のリクエスト時に返却された「NextPageToken」の値を指定してください。PageTokenを指定した場合、他のパラメーターは無視されます。 |
X-Yamaha-YNO-MngAPI-Version | string Example: 1.0 管理APIのバージョン 指定しない場合、最新バージョンで動作します。 |
{- "Meta": {
- "MngApiVersion": "1.0"
}, - "Data": {
- "Type": "ExecuteCommand",
- "Results": {
- "Devices": [
- {
- "Status": "SUCCESS",
- "SerialNumber": "M4Y000000",
- "CommandResults": [
- {
- "Output": [
- "CWMP : 正常 (2023/06/26 16:28:17)",
- "XMPP : 正常",
- "GFW : 正常",
- "LAS : 正常",
- "オペレーターID : demo",
- ""
], - "Command": "show status yno",
- "ExitCode": "SUCCESS"
}, - {
- "Output": [
- ""
], - "Command": "",
- "Exitcode": "SKIPPED"
}, - {
- "Output": [
- "エラー: コマンド名を確認してください"
], - "Command": "aaaaaa",
- "Exitcode": "ERROR"
}
]
}, - {
- "Status": "TIMEOUT",
- "SerialNumber": "S4H000000",
- "CommandResults": [ ]
}
]
}
}
}