Cisco MerakiダッシュボードAPI

APIドキュメンテーション

MerakiのAPIの詳細については、専用のAPIドキュメンテーションWebサイト http://meraki.com/developersを参照してください。APIの参照ドキュメンテーションは、http://postman.meraki.comのPostmanコレクションにあります。Postmanコレクションは、APIコールをテストするためにPostmanアプリケーションにインポートできます。 

APIアクセスの有効化

APIにアクセスするには、最初にOrganization（オーガナイゼーション） > Settings（設定） > Dashboard API access（ダッシュボードAPIアクセス）で、オーガナイゼーションのAPIを有効化します。 

 

APIを有効化したら、プロファイル ページに移動して、APIキーを生成します。APIキーはダッシュボード管理者アカウントに関連付けられます。 自分のプロファイルのAPIキーを生成、失効、および再生成できます。

 

APIリクエスト

すべてのリクエストでは、リクエスト ヘッダーでAPIキーを指定する必要があります。さらに、APIキーをURLで指定する必要があります。 APIは、リソースの存在が不正ユーザに漏れることを防ぐために、APIキーが欠落しているか正しくないリクエストに対して（403ではなく）404を返します。

X-Cisco-Meraki-API-Key: <secret key>

APIバージョンをURLで指定する必要があります。

https://api.meraki.com/api/v0/<resource>

APIバージョンがリリースされると、下位互換性を確保するための変更のみが行われます。下位互換性を確保するための変更には、以下のものがあります。

• 新しいAPIリソースを追加する

• オプションの新しいリクエスト パラメータを既存のAPIメソッドに追加する

• 新しいプロパティを既存のAPIレスポンスに追加する

• 既存のAPIレスポンスのプロパティの順番を変更する

APIのIDは、型があいまいなストリングです。たとえば、<network_id>はストリング「126043」ですが、<order_id>は「4S1234567」のように文字を含む場合があります。クライアント アプリケーションでは、これらを数値として解析しないでください。数値のように見えるIDであっても、IDが長すぎるため、（数値型がIEEE 754の浮動小数点のみである）Javascriptで精度を落とすことなくエンコードできない場合もあります。

 

APIの動詞は、通常のREST規約に従います。

• GETは、IDが指定されたかどうかによって、リソースの値またはリソースのリストを返します。
  • /v0/organizationsのGETはオーガナイゼーションのリストを返します
  • /v0/organizations/<org_id>のGETは特定のオーガナイゼーションを返します。
• POSTは新しいリソースを追加します
  • /v0/organizations/<org_id>/adminsへのPOST
  • POSTは、べき等以外のその他の変更を実行します 
• PUTはリソースを更新します
  • PUTはべき等です。つまり、リソースを更新し、リソースがまだ存在しない場合は最初に作成します。
  • PUTはリソースのすべてのフィールドを指定する必要があります。APIは省略されたフィールドをデフォルト値に戻します。
• DELETEはリソースを削除します。

ステータス コードおよびエラー コード

APIからのレスポンスでは、一般的に標準のHTTPステータス コードが使用されます。いくつか例を示します。

• 400：Bad Request（不正なリクエスト）- 不正な形式のリクエストまたはパラメータの未指定などの正しくない操作が実行されました。
• 403：Forbidden（禁止）- 操作を行う権限がありません。
• 404：Not found（検出不能）- そのようなURLが存在しないか、APIまたはオーガナイゼーションへのアクセス権がありません。 
• 429：Too Many Requests（リクエストが多すぎる）- オーガナイゼーションに対して1秒間に5回を超えるコールを送信し、レート制限がトリガーされました。これは、複数のオーガナイゼーションに対してAPIコールが行われ、そのうちのいずれかのオーガナイゼーションでレート制限がトリガーされた場合にも当てはまります。

レスポンス コードが具体的でないため問題の原因を判別できない場合、エラー メッセージは次のようにJSON形式でレスポンスに含められます。

{
    "errors": [
       "VLANs are not enabled for this network"
    ]
}

オーガナイゼーション

X-Cisco-Meraki-API-Keyに指定されているAPIキーのオーガナイゼーション リストを取得する

GET https://api.meraki.com/api/v0/organizations
Response code: 302
Response: redirect to https://n123.meraki.com/api/v0/organizations

リクエストはn123.meraki.comにリダイレクトされます。DELETE、POST、PUTなどの状態を変更するAPIコールを含むすべてのAPIコールで、302が発生することがあります。GETがリダイレクトされる場合、ステータス コードは302になります。GET以外がリダイレクトされる場合、ステータス コードはPostmanの場合は307、それ以外のクライアントの場合は308になります。クライアント アプリケーションはこれらのリダイレクトに従う必要があります 。リダイレクトを発行するホストによるアクションは実行されないため、べき等以外のリクエストであっても新しいホストで安全に再試行できます。

リダイレクト リンクに送信されるクエリ：

GET https://n123.meraki.com/api/v0/organizations
Response code: 200
Response body: [ {“id”: <org_id>, “name”: “Test Organization” } ]

特定のオーガナイゼーションについてのメタデータを取得する：

GET https://api.meraki.com/api/v0/organizations/<org_id>
Response code: 200
Response body: { "id": <org_id>, "name": "Test Organization" }

ほとんどのHTTPライブラリおよびクライアントはGET以外のHTTP動詞を使用するリダイレクトに従わず、その代わりにリダイレクトに従うが、HTTP動詞をGETに置換することがあります。その結果、DELETE、POST、またはPUTのリクエストが、あたかもGETがリクエストされたかのように見える場合もあります。これを避けるには、操作するオーガナイゼーションに対して最初にGETを実行し、操作するURLを格納し、その後でそのURLを後続のリクエスト（特に状態を変更するリクエスト）に使用してください。

新しいオーガナイゼーションを作成する：

POST https://api.meraki.com/api/v0/organizations
Request body: { “name”: “Second Test Organization” }
Response code: 201 
Response body: { "id": <new_org_id>, name: "Second Test Organization" }

新しいオーガナイゼーションは設定解除されます。ただし例外として、オーガナイゼーションを作成した管理者は、新しいオーガナイゼーションに対する完全なオーガナイゼーション書き込みアクセス権を持ちます。APIのクライアントは必要に応じて、管理者を追加し、新しいオーガナイゼーションから管理者の作成を削除することができます。

ネットワーク

オーガナイゼーション内のネットワークを一覧表示する： 

GET https://api.meraki.com/api/v0/organizations/<new_org_id>/networks
Response code: 200
Response body: [ { "id": <network_id>, "name": "Test Network", "organization_id": <new_org_id>, "type": "wireless",
   "timeZone": "America/Los_Angeles", "tags": " test "
} ]

新しいネットワークを作成する：

POST https://api.meraki.com/api/v0/organizations/<org_id>/networks
Request body: { “name”: “Test Network 2”, “organizationId”: <org_id>, “type”: “appliance”}
Response code: 201
Response body: { “id”: <network_id>, “name”: “Test Network 2”, “organization_id”: <org_id>, “type”: “appliance”, “tags”: null }

有効なネットワークは、「appliance」、「switch」、「wireless」、「systemsManager」、または「camera」です。統合ネットワークを作成するにはこれらを組み合わせて使用します。たとえば、「appliance wireless」となります。 

ライセンスおよびデバイス

オーガナイゼーションへのデバイス、ライセンス キー、または注文を要求します。注文によって要求する場合、注文内のすべてのデバイスおよびライセンスが要求されます。ライセンスがオーガナイゼーションに追加され、デバイスがオーガナイゼーションのインベントリに配置されます。これらの3つの種類の要求は相互排他的のため、1つのリクエストで実行できません。「licenseMode」パラメータは「renew」または「addDevices」のいずれかとすることができます。「addDevices」はライセンス制限を増加し、「renew」は期限切れまでの期間を延長します。このパラメータは、licenseKeyによって要求される場合に必要です。詳細については、こちらの記事を参照してください。

POST https://api.meraki.com/api/v0/organizations/<org_id>/ claim
Request body: { "order": "4CXXXXXXX" }
Response code: 200
Response body: <empty>

SNMP設定

オーガナイゼーションのSNMP設定を行います。SNMPv2のコミュニティ ストリングが応答に含まれます。これは同じURLへのGETによって取得することもできます。

GET https://api.meraki.com/api/v0/organizations/<org_id>/snmp
Request body: { "v2cEnabled": true, "v3Enabled": true, "v3AuthMode": "SHA", "v3AuthPass", <secret>, "v3PrivMode": "AES128", "v3PrivPass": <secret>, "allowedIPs": ["5.6.7.8"] }
Response code: 200
Response body: { "v2Enabled": true, “v2CommunityString”: <secret>, "v3Enabled": true, "authMode": "SHA", "authPass", <secret>, "privMode": "AES128", "privPass": <secret>, "allowedIPs": ["5.6.7.8"] }

管理者 

オーガナイゼーションの管理者を一覧表示します：

GET https://api.meraki.com/api/v0/organizations/<org_id>/admins
Response code: 200
Response body: [ { "name": "Jane Doe", "email": "jane@doe.com", "orgAccess": "full","id": <admin_id> } ]

オーガナイゼーション アクセスは、「full」、「read-only」、または「none」に指定できます。
 

1つのネットワークのみへの権利を持つ新しい管理者を追加する：

POST https://api.meraki.com/api/v0/organizations/<org_id>/admins/
Request body: { "name": "John Doe", "email": "john@doe.com", "orgAccess": "none", "networks": [{ "id": <network_id>, "access": "full" }
Response code: 201
Response body: { “id”: <admin_id>, "name": "John Doe", "email": "john@doe.com", "orgAccess": "none", "networks": [{ "id": <network_id>, "access": "full" }]

ネットワークの有効なアクセス レベルは「full」、「read-only」、「monitor-only」、および「guest-ambassador」です。クライアントは次のように「networks」フィールドを「tags」に置換することによって、タグにより管理者アクセスを付与することもできます。

"tags": [{ "tag": "foo", "access": "read-only" }],

タグについての有効なアクセス レベルはネットワークと同じです。クライアントはPUTを使用してadmin_idを指定することによって管理者を更新できます。

管理者を削除する：

DELETE https://api.meraki.com/api/v0/organizations/<org_id>/admins/<admin_id>
Response code: 204
Response body: <empty>