Cisco MerakiダッシュボードAPI

Last updated
Save as PDF

概要

MerakiダッシュボードAPIは、ソフトウェアがMerakiクラウドプラットフォームおよびMerakiマネージドデバイスと直接対話するためのインターフェースです。このAPIには、Merakiダッシュボードと通信するソフトウェアおよびアプリケーションを構築するためのエンドポイントとして知られているツールセットが含まれており、プロビジョニング、一括での設定変更、監視、ロールベースのアクセス制御などの事例に使用されます。ダッシュボードAPIは、URLへのHTTPSリクエストおよび人間が判読可能な形式のJSONを使用する、最新のRESTful APIです。ダッシュボードAPIは、多くの目的で使用できるオープンエンドツールです。このツールの実際の活用事例を以下に示します。

新しいオーガナイゼーション、管理者、ネットワーク、デバイス、VLAN、SSIDを追加する
自動化スクリプトを使用して数千もの新しいサイトを数分でプロビジョニングする
新しい従業員のテレワーカーデバイスを自動的にオンボーディングおよびオフボーディングする
店長や現場技師などの独自の使用事例のために独自のダッシュボードを作成する

注：API呼び出しのボリュームは、オーガナイゼーションあたり毎秒5回に制限されています。

API ドキュメンテーション

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

APIアクセスの有効化

API アクセスはデフォルトで有効になっていますが、アクセスするためには API キーの生成が必要です。

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

注： APIキーによって、すべてのオーガナイゼーションへの認証用のAPIが有効化されるため、APIキーは安全に保管してください。APIキーが共有された場合、APIキーをいつでも再生成することができます。これにより既存のAPIキーは失効します。

注1: 管理者ごとに生成できる API キーは 2 つまでです。API キーを 2 つ生成すると API キー生成ボタンが表示されなくなります。新しく API キーを生成する必要がある場合には既存の API キーをひとつ失効させてください。

注:2 なお、SAMLダッシュボード管理者は、APIキーを表示および生成できません。

API & Webhooks ダッシュボード

API キーと Webhook の設定は専用のダッシュボードページ(オーガナイゼーション > API & Webhooks) でも行なえます。

注 : このページは現在オーガナイゼーション管理者のみアクセス可能です。

ダッシュボードAPIの使用

APIリクエスト

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

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

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

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

注: 中国でホストされているオーガナイゼーションは "api.meraki.cn" を使用してください。

カナダ用ダッシュボードでホストされているオーガナイゼーションは "api.meraki.ca" を使用してください。

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

新しいAPIリソースを追加する
オプションの新しいリクエストパラメータを既存のAPIメソッドに追加する
新しいプロパティを既存のAPIレスポンスに追加する
既存のAPIレスポンスのプロパティの順番を変更する

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

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

GETは、識別子の有無により、リソースの値またはリソースのリストを返します。
- /v1/organizations のGETはオーガナイゼーションのリストを返します
- /v1/organizations/<org_id>のGETは特定のオーガナイゼーションを返します。
POSTは新しいリソースを追加します
- /v1/organizations/<org_id>/adminsへのPOST
- POSTは、べき等でないその他の変更を実行します
PUTはリソースを更新します
- PUTはべき等です。つまり、リソースを更新し、リソースがまだ存在しない場合は最初に作成します。
  ※べき等(冪等)とはある操作を複数回実行しても、最初の実行以降にはシステムの状態に変化をもたらさない性質を指します
- PUTはリソースのすべてのフィールドを指定する必要があります。APIは省略されたフィールドをデフォルト値に戻します。
DELETEはリソースを削除します。

注：呼び出しのボリュームは、オーガナイゼーションあたり毎秒5回に制限されています。

注：中国のダッシュボードでホストされているオーガナイゼーションについては、api.meraki.comでなくapi.meraki.cnを使用してください。

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

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

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

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

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

例

リクエストとレスポンスの例を次に示します。これらは包括的なものではありません。包括的なAPIエンドポイントのリストとその詳細については、上記のオンラインドキュメンテーションのURLを参照してください。

オーガナイゼーション

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

GET https://api.meraki.com/api/v1/organizations
レスポンス コード：302
レスポンス：https://n123.meraki.com/api/v1/organizationsにリダイレクト

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

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

GET https://n123.meraki.com/api/v1/organizations
レスポンス コード：200
レスポンス本文：[ {“id”: <org_id>, “name”:“Test Organization” } ]

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

GET https://api.meraki.com/api/v1/organizations/<org_id>
レスポンス コード：200
レスポンス本文：{ "id": <org_id>, "name":"Test Organization" }

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

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

POST https://api.meraki.com/api/v1/organizations
リクエスト本文：{ “name”:“Second Test Organization” }
レスポンス コード：201 
レスポンス本文：{ "id": <new_org_id>, name:"Second Test Organization" }

新しく作成したオーガナイゼーションでは作成した管理者がそのオーガナイゼーションでフルアクセスの権限を有する設定以外何も設定されません。APIのクライアントは必要に応じて、管理者を追加し、新しいオーガナイゼーションから管理者の作成を削除することができます。

注： APIでは完全なオーガナイゼーション書き込みアクセスを持つ最後の管理者を削除することをクライアントに許可しません。ただし、この操作を行うと、オーガナイゼーションが設定不能になります。

ネットワーク

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

GET https://api.meraki.com/api/v1/organizations/<new_org_id>/networks
レスポンス コード：200
レスポンス本文：[ { "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/v1/organizations/<org_id>/networks
リクエスト本文：{ “name”:“Test Network 2”, “organizationId”: <org_id>, “type”: “appliance”}
レスポンス コード：201
レスポンス本文：{ “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/v1/organizations/<org_id>/ claim
リクエスト本文：{ "order":"4CXXXXXXX" }
レスポンス コード：200
レスポンス本文：<empty>

SNMP設定

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

GET https://api.meraki.com/api/v1/organizations/<org_id>/snmp
リクエスト本文：{ "v2cEnabled": true, "v3Enabled": true, "v3AuthMode":"SHA", "v3AuthPass", <secret>, "v3PrivMode":"AES128", "v3PrivPass": <secret>, "allowedIPs": ["5.6.7.8"] }
レスポンス コード：200
レスポンス本文：{ "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/v1/organizations/<org_id>/admins
レスポンス コード：200
レスポンス本文：[ { "name":"Jane Doe", "email": "jane@doe.com", "orgAccess": "full","id": <admin_id> } ]

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

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

POST https://api.meraki.com/api/v1/organizations/<org_id>/admins/
リクエスト本文：{ "name":"John Doe", "email": "john@doe.com", "orgAccess": "none", "networks": [{ "id": <network_id>, "access": "full" }
レスポンス コード：201
レスポンス本文：{ “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/v1/organizations/<org_id>/admins/<admin_id>
レスポンス コード：204
レスポンス本文：<empty>

概要