Home > General Administration > Other Topics > The Cisco Meraki Dashboard API > Cisco MerakiダッシュボードAPI

Cisco MerakiダッシュボードAPI

概要 

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にアクセスするには、最初にOrganization(オーガナイゼーション) > Settings(設定) > Dashboard API access(ダッシュボードAPIアクセス)で、オーガナイゼーションのAPIを有効化します。 

 

image3.png

 

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

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

 

image2.png

 

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

 

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

  • GETは、識別子の有無により、リソースの値またはリソースのリストを返します。

    • /v0/organizations のGETはオーガナイゼーションのリストを返します

    • /v0/organizations/<org_id>のGETは特定のオーガナイゼーションを返します。

  • POSTは新しいリソースを追加します

    • /v0/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/v0/organizations
レスポンス コード:302
レスポンス: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
レスポンス コード:200
レスポンス本文:[ {“id”: <org_id>, “name”:“Test Organization” } ]

 

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

GET https://api.meraki.com/api/v0/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/v0/organizations
リクエスト本文:{ “name”:“Second Test Organization” }
レスポンス コード:201 
レスポンス本文:{ "id": <new_org_id>, name:"Second Test Organization" }

 

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

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

ネットワーク 

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

GET https://api.meraki.com/api/v0/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/v0/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/v0/organizations/<org_id>/ claim
リクエスト本文:{ "order":"4CXXXXXXX" }
レスポンス コード:200
レスポンス本文:<empty>

SNMP設定 

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

GET https://api.meraki.com/api/v0/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/v0/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/v0/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/v0/organizations/<org_id>/admins/<admin_id>
レスポンス コード:204
レスポンス本文:<empty>

 

Last modified

Tags

Classifications

This page has no classifications.

Explore the Product

Click to Learn More

Article ID

ID: 9689

Explore Meraki

You can find out more about Cisco Meraki on our main site, including information on products, contacting sales and finding a vendor.

Explore Meraki

Contact Support

Most questions can be answered by reviewing our documentation, but if you need more help, Cisco Meraki Support is ready to work with you.

Open a Case

Ask the Community

In the Meraki Community, you can keep track of the latest announcements, find answers provided by fellow Meraki users and ask questions of your own.

Visit the Community