Yamaha Network Organizer (YNO) 管理APIリファレンス

HTTPリクエストは以下の形式で送信します。

METHOD BASE_URL/PATH/PATH_PARAMETERS?QUERY_PARAMETERS
HEADER

BODY

各パラメーターには以下を指定してください。

• METHOD: 各エンドポイントの仕様を参照してください。
• BASE_URL: https://yno-mngapi.netvolante.jp
• PATH: 各エンドポイントの仕様を参照してください。
• PATH_PARAMETERS: 各エンドポイントの仕様を参照してください。
• QUERY_PARAMETERS: 各エンドポイントの仕様を参照してください。
• HEADER

  キー名	説明
  X-Yamaha-YNO-MngAPI-Key	APIキーを指定してください。 管理APIは、APIキーを利用して認証を行います。APIキーは、YNOマネージャーのGUIで生成できます。生成方法は、YNO操作マニュアルの「APIキーを生成する」を参照してください。 以下の場合、認証エラーになります。 APIキーが正しくない APIキーが有効期間外
  X-Yamaha-YNO-MngAPI-Version	管理APIには、エンドポイント全体で1つのバージョンが付与されています。HTTPクライアントは、リクエスト送信時に管理APIのバージョンを指定します。YNOマネージャーは実際に動作している管理APIのバージョンをレスポンスに含めて返却します。 バージョンは「メジャーバージョン.マイナーバージョン」のフォーマットで管理されます。 マイナーバージョンは、エンドポイントに互換性のある変更が発生した場合に更新されます。(例: 1.1) HTTPリクエストで指定されているマイナーバージョンが古い場合 (例: 1.0) でも、リクエストは受け付けられます。 実際の処理は、新しいマイナーバージョンで動作します。 メジャーバージョンは、エンドポイントに互換性のない変更が発生した場合に更新されます。(例: 2.0) メジャーバージョンが更新された場合、変更内容によって、HTTPクライアントの修正が必要になる場合があります。 古いメジャーバージョン (例: 1.x) は、弊社が別途定める移行期間を経たのちに廃止されます。 HTTPクライアントが廃止されたバージョンを指定してリクエストを送信すると、エラーになります。 HTTPリクエストでバージョンを指定しない場合、最新バージョンで動作します。
  Content-Type	HTTPメソッドがPOSTまたはPUTの場合、「application/json」を指定してください。

• BODY: 各エンドポイントの仕様を参照してください。

ルーターを検索する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のリクエストには、以下の制限があります。

• 1分あたりのAPIコール回数 (リクエスト回数): 180回まで
• 1日あたりのAPIコール回数 (リクエスト回数): 30,000回まで
• 1日あたりのデータ転送 (レスポンスのデータ量): 100MBまで

管理APIへのリクエスト結果が「失敗」の場合も、上記の制限に加算されます。制限を超えて管理APIにリクエストした場合、リクエストに失敗し、HTTPレスポンスのステータスコードに「429」が返却されます。

1日あたりの管理APIの使用状況は、YNOマネージャーのGUIの「管理API使用状況」画面で確認できます。

情報を取得するエンドポイントでは、一度に取得できるデータ数に上限があります。すべてのデータを取得するためには、リクエストの送信が繰り返し必要な場合があります。

取得できるデータ数の上限を超えるようなリクエストを送信した場合、以下のデータが返却されます。

• 取得上限までのデータ
• 残りのデータを取得するためのパラメーター (NextPageTokenまたはNextSearchAfter)

■NextPageToken

NextPageTokenの値を、次のリクエストのPageTokenに指定して送信することで、続きのデータを取得できます。たとえば、ルーターを検索するAPIは、以下のような手順で使用します。

1. リクエストボディーに検索条件を指定して、リクエストを送信する
2. NextPageTokenが返却された場合、リクエストボディーにPageTokenを指定して再度リクエストを送信する
   
   • PageToken以外のパラメーター (検索条件など) を指定する必要はありません。指定した場合、PageToken以外のパラメーターは無視されます。
3. 再度NextPageTokenが返却された場合、リクエストボディーに新しいPageTokenを指定してリクエストを送信する
4. NextPageTokenが返却されなくなるまで、PageTokenを指定したリクエストの送信を繰り返す

NextPageTokenには、5分間の有効期限があります。有効期限が切れてしまった場合、1のリクエストの送信からやりなおす必要があります。

■NextSearchAfter

NextSearchAfterの値を、次のリクエストのSearchAfterに指定して送信することで、続きのデータを取得できます。たとえば、機器統計情報を取得するAPIは、以下のような手順で使用します。

1. リクエストボディーに検索条件を指定して、リクエストを送信する
2. NextSearchAfterが返却された場合、リクエストボディーに1で指定していた検索条件とSearchAfterを指定し、再度リクエストを送信する
   
   • SearchAfter以外の検索条件は、1で指定していた内容をそのまま指定してください。SearchAfter以外の検索条件を変更した場合、動作は不定となります。
   • SearchAfterには、前回のリクエスト時に返却された「NextSearchAfter」の値を指定してください。返却された値以外を指定した場合、動作は不定となります。
3. 再度NextSearchAfterが返却された場合、2のリクエストボディーに新しいSearchAfterを指定して、リクエストを送信する
4. NextSearchAfterが返却されなくなるまで、SearchAfterを指定したリクエストの送信を繰り返す

タスクを使用することで、機器に特定のアクションを実行できます。

現在、タスクでは以下の機能を利用できます。

• ルーターへのコマンド実行

タスクは非同期で実行されます。そのため、タスクの登録と実行結果の取得は別々のAPIにリクエストを送信する必要があります。以下の手順でタスクを実行します。

1. タスクを登録する
   ・タスクを登録するAPI (POST /tasks) で、タスクを登録します。
   ・登録したタスクのTaskIdが返却されます。これは、タスクの実行結果を取得するときに使用します。
2. TaskIdを使用して、タスクの実行結果を取得する
   ・タスクの実行結果を取得するAPI (GET /tasks/TaskId) で、タスクの実行結果を取得します。
   ・タスクの実行が完了するまで、実行結果を取得できません。そのため、実行結果を取得できるまで、リクエストを繰り返す必要があります。

タスクは、登録してから1日経過すると削除されます。

YNOマネージャーのユーザー管理のしくみについては、YNO操作マニュアルを参照してください。