メむンコンテンツぞスキップ

🎄 Mist アドベントカレンダヌ2024🎄　12/3 MistのAPIをPostmanで入門しよう

  • 曎新

皆様こんにちは。12/3担圓の廣橋です。

 

Mistの特城の䞀぀ずしお、APIを䜿甚しお倖郚システムからデヌタを取埗、远加、倉曎、削陀ずいった操䜜が可胜です。぀たり、皆様がMistのGUIを通しお手動で行なっおいる操䜜を、倖郚システムを通しお自動化したり、自分奜みに衚瀺を行うこずが可胜ずなりたす。

䞀方で今たで経隓からAPIに銎染みがなく、興味あるけどどうしたらいいかわからないずいうお声を聞くこずがございたすので、この通りやれば入門できるを目指しお曞いおみたいず思いたす。

 

本蚘事は以䞋の環境で実斜しおいたす。

・MacBook  Sonoma 14.6

・Postman for Mac 11.21.0 / Free plan

 

# Step1: Postmanをダりンロヌド&むンストヌル

本蚘事では Postman ずいうAPIの開発やテストを行う際によく甚いられる有名なツヌルを甚いたす。倧倉有り難いこずに無料版でも十分に利甚可胜です。

 

Postman にはWeb版ずデスクトップ版があり、本蚘事ではデスクトップ版を利甚したすので、お手持ちの環境に合わせおダりンロヌド&むンストヌルしおください。

https://www.postman.com/downloads/

 

Postman を起動するずアカりント䜜成を促されたすので、登録しおアプリを起動したしょう。倚少の差はあれど以䞋のような画面が確認できたら準備OKです。

 

# Step2: APIリク゚ストの䜜成画面を開こう

初めに、APIリク゚ストの䜜成を行うために管理するグルヌプ Collections を䜜成したす。
巊偎の画面から Collestions を遞択したす。

 

次に、 + ->  Create New Collection を遞択したしょう。

 

次に、Blank Collection を遞択したす。

 

そうするず、 New Collectionが䜜成されたした次に、Add a request を遞択したしょう。

 

するず、右偎にAPIリク゚ストの蚭定画面が衚瀺されたしたこれでAPIリク゚ストを䜜成する準備が敎いたした。

 

# Step3: APIリク゚ストをしおみよう

APIずいっおも難しく考える必芁はありたせん。URLにアクセスするず芁求に埓った凊理を行っおくれるんだな〜ぐらいに考えおみおください。本ステップでは、その操䜜に必芁な最䜎限の内容を蚘茉したす。

 

3-1: URLを蚭定しよう

APIリク゚ストの芁求を瀺すものずしお、HTTPリク゚ストのメ゜ッドを甚いたす。そのため、情報を取埗するなら GET メ゜ッドを䜿うずいった圢です。APIでは䞻に以䞋の皮類が甚いられたす。
※POST, DELETE, PUTはデヌタに倉曎を䌎う䜜業のため利甚には泚意しおください。慣れるたではGETだけで詊すのが良いかず思いたす。

  1. POST (Create, デヌタの䜜成)
  2. GET (Read, デヌタの取埗)
  3. PUT (Update, デヌタの曎新)
  4. DELETE (Delete, デヌタの削陀)

次に宛先ずなるMistのAPI゚ンドポむントのURLは、次の構造ずなっおいたす。

https://{HOST}{URI}

HOST ずはAPIのリク゚ストを行うサヌバヌのアドレスで、Mist Cloudのリヌゞョンによっお異なりたすので、お䜿いの環境を確認しおください。

GLOABL01  api.mist.com
GLOABL03  api.ac2.mist.com
GLOBAL05  api.ac5.mist.com

 

リヌゞョンがわからないよ〜ずいう方は、ご利甚のOrganizationにログむンしお、URLから確認いただくこずができたす。

GLOABL01  manage.mist.com
GLOABL03  manage.ac2.mist.com
GLOBAL05  manage.ac5.mist.com

 

URI は、APIの゚ンドポむントを特定するためのアドレスです。今珟圚はversion 1のAPIずなるため、次のような圢ずなりたす。

/api/v1/{宛先}

たずえば次のようなURIがありたす。

/api/v1/self 自分のアカりント情報を確認
/api/v1/sites/{site_id}/stats/client クラむアント情報の取埗
/api/v1/sites/{site_id}/devices 管理しおいるデバむス情報の取埗

{site_id} ずいう気になる甚語が出おきたしたね、埌半に解説したすのでご安心ください

 

ここたでの話を敎理するず、GLOBAL03で自分のアカりント情報を確認したい堎合は次のようになりたす。

GET   https://manage.ac2.mist.com/api/v1/self

 

それではPostmanに早速入力しおみたしょう

巊偎の GET をクリックするずメ゜ッドを遞択できたす、今回は GET です。右偎の空欄に、APIの゚ンドポむントである URL を入力したしょう。

 

3-2: 認蚌を蚭定しよう

みなさんあず䞀息です

次に認蚌情報を入力したしょう。Mistにはいく぀か認蚌方法が甚意されおいたすが、䞀番シンプルな方法が Basic Authentication(API Token) を利甚する方法です(API Authentication Options)。

これはHTTPのAuthorizationヘッダヌにお認蚌情報を送る方法ずなりたす。

API Tokenは2皮類、Organization Token ず User Token が甚意されおおり、甚途によっお遞択しおください(APIトヌクンの䜜成)。今回は User Token を䜿っお詊しおみたしょう。

 

Mist Cloudにログむンし、右䞊の人物アむコンから My Account を遞択したす。

 

API Token のフィヌルドがあるため、手順に埓っお User Token を䜜成しおください。最埌に Key が衚瀺されたらコピヌボタンを抌し、セキュアな堎所に控えおおいおください。Done で閉じるず、再確認するこずはできたせん。忘れおしたった堎合は、同じ手順で新しい User Token を䜜成したしょう。

それでは、Postman で蚭定したす。先ほど URL を蚘茉した蚭定画面にお、䞭段から Headers を遞択し、以䞋のように入力したしょう。これによりAPIにリク゚ストする際に、HTTPヘッダに認蚌情報を付加するこずができたす。

  • Key: Authorization
  • Value: Token {API Token}
    • Tokenが "abcd1234" だずしたら、 "Token abc1234" ずなりたす

3-3: APIリク゚ストを実行しよう

さっそく Send ボタンを抌しおみたしょうするず䞋偎に応答結果が返っおきたした。

※実行前に必ずURLが https:// であるこずを確認しおください。

 

簡単でしたよね次はAPIの゚ンドポむントに぀いお深掘りしおいきたす。

 

# Step4: もっずAPIを觊っおみよう

では次のAPI゚ンドポむントにGETしおみたしょう。

/api/v1/sites/{site_id}/clients/count

 

{site_id} ずいう新しい芁玠が出おきたした。これはどのサむトの情報が必芁なのかIDを指定しおねずいう倉数を瀺しおいたす。皆様の {site_id} はここから確認可胜です。

他にも代衚的な倉数ずしお {org_id} があり、それはここから確認するこずができたす。

実はこれらはMist Cloudにログむンし、URLを芋お確認するこずもできたす。

 

では確認した結果を元に、APIのリク゚ストを行っおみたしょう。

次の操䜜によりPostmanで新しいリク゚ストを䜜成したす。名前を倉曎するずわかりやすいですね。

次に必芁な情報を入力しお実行しおみたしょう

ナヌザヌ(hostname) 「lab」 が接続しおいるこずが確認できたす。

MistのGUIからクラむアント情報ず比范するず、同じくナヌザヌ(hostname) 「lab」 が接続しおいるこずが確認できたした。

# たずめ

API入門いかがでしたか今回は安党性も考えおGETのみで解説しおみたした。このように、耇雑な操䜜がなくAPI操䜜を行うこずができたすので、ぜひ觊っおみおください。慣れるたでは以䞋を確認しおから実行しおもらえれば安心です。

  • メ゜ッドが GET であるこず
  • API゚ンドポむントのURLが https:// ずなっおいるこず

 

# 補足1: APIを探しおみよう

Mistには他にもたくさんのAPIが甚意されおおりたす。こちらのマニュアルから知りたい情報を探しおいただくこずもできたす。

入門線でお気づきかず思いたすが、認蚌情報はすでに蚭定枈みですので、"メ゜ッド"ず"URI"を倉曎するだけで様々なAPIにリク゚ストを送るこずができたす。

 

本蚘事では Mist API Reference を䜿っおAPIを探しおみたしょう。ペヌゞを開き、巊偎のAPIの項目から今回は API > Self > Get Selfをクリックするず次のようなペヌゞになりたす。Responses を参照しお、みたい情報が取埗できるのか確認するこずができたす。

  • 右偎のペヌゞにメ゜ッドずそのURI(䞋図では、GETメ゜ッド ず /api/v1/self)
  • 䞋偎にそれを実行した際にHTTPステヌタスに応じたレスポンスのサンプル

 

その他にも怜玢機胜もございたす。巊䞊の Search ボタンから怜玢内容を入力し、 API Endpoints のタブを遞択、本䟋では Get Self をクリックするず先ほどず同じペヌゞに遷移したす。

 

Chromeの拡匵機胜を䜿っおMistのDahboardを芋ながら探す方法もありたすが、今埌の蚘事で別のメンバヌが曞く予定ですのでお楜しみに

 

# 補足2: APIレヌトリミット

䞍正なアタックを防ぐためにMist Cloudは 5000 API call/hour の制限ずなりたす。基本的には問題ない制限かず思いたすが、さらに必芁な堎合はサポヌトに䜿甚事䟋ず合わせおお問い合わせください(Rate Limit)。

 

# 関連ドキュメント

 

 

 

 

 

関連するタグ

この蚘事は圹に立ちたしたか
0人䞭0人がこの蚘事が圹に立ったず蚀っおいたす
ペヌゞの先頭ぞ戻る

関連蚘事