はじめに
Auth0のドキュメントに記載されているAPI操作は、curlコマンドで記載されています。
一方で、PowerShell標準の Invoke-webRequest
やInvoke-RestMethod
を用いて操作するといった日本語情報が少ないと思ったため、GETとPOSTリクエストの方法をまとめました。
ついでに、Auth0にいる全ユーザー数を取得する方法も共有します。
Windowsのcurl事情
CLIから通信を行える便利コマンド curl
は元々UNIX系のコマンドで、もともとWindowsにはインストールされていませんでした。
こちらの記事によると、2018年のWindows 10 Ver.1803からCurl.exeがWindowsにデフォルトで使えるようになったそうです。そこからは、コマンドプロンプトなら、curl
、PowerShellの場合curl.exe
と打てばcurlが使えます。
ここで大事なことですが、2018年までcurlが使えなかった時代の名残なのか、 PowerShellの場合、curl
と打つとWindows用のcurl
であったInvoke-WebRequest
が実行されてしまいます(curl.exeだとcurlが動くが、curlにはinvokeコマンドのエイリアスが貼ってある)。普段Windows環境を触らない人にとって、高度な罠ですね。
PS C:\Users\xxxx> curl |
そのため、筆者のようにPowerShellでは 一般にイメージする curl
がないものだと認識し、Invoke-webRequest
や Invoke-RestMethod
を使う必要があると勘違いする人も少なくないと思います。今回の記事は一連のAuth0のドキュメントにあったcurlコマンドをInvoke-RestMethodに置換して実行する流れを、一晩かけて勢いでまとめた記事です。
すべてを書き終えた後、先輩社員にcurl.exe
すればcurl出来るよと言われ悲しくなりましたが、2023年10月、2027年1月までサポートを受けているWindows Server 2012、2016にはcurlがないと思われるので、そういった環境を扱う方には有用だと思います。ちなみに、Windows Server 2019には curl.exe
がありましたので、素直にそちらで操作すると良いでしょう。
注意ですが、この記事に記載しているcurlコマンドをコマンドプロンプト上で動かす場合は、\
のエスケープと、改行を消す必要があります(記事上では読みやすさのために改行を入れています)。
結論から話すと
以下のコマンドで動きます。
- token取得(postリクエスト)
$client_id = "xxx" |
- output.txtからtokenをコピーして2のコマンドを打つ
- 全ユーザー数取得コマンド(getリクエスト)
$token = "copyAndPasteHere" |
- output.txt が不要になれば削除します
rm .\output.txt |
操作の流れ
Auth0にいる総ユーザー数を取得を Invoke-RestMethod
で記載する方法を共有します。
基本的には以下の2つのコマンドをInvoke-RestMethod
で代替します。
- APIを利用するtokenを取得する(POSTリクエスト)
- 総ユーザー数取得APIを打つ(GETリクエスト)
1. APIを利用するtokenを取得する(POSTリクエスト)
ユーザー数取得に使う Auth0 User Management API を利用するためのtokenをまずは取得します。
User Management APIの利用権限のあるAPIのtoken取得コマンドが、API設定のTestタブに以下の画像のように書いてあるので参照します。tokenを取得するcURLコマンド
と、すごく親切にバックエンドでよく用いる言語での取得方法まで記載しているので参考になります。
![](/images/20221130a/0.png)
curl --request POST \ |
観察
まず元のCURLが何やってるか見ます。
- POSTリクエスト
- content typeがapplication/json形式
- dataにjson文字列でclient認証情報を渡している
dataとありますが HTTPリクエストではbody とも呼びます。ここまでで、 Invoke-RestMethod
でやることは「JSONをPOSTするリクエストを作れば良い」ということが分かります。
公式ドキュメント見る
2022年11月時点ではpowershell-7.3が最新のようで、公式ドキュメントはこれです。
Invoke-RestMethod |
中々難しそうですが、コレを見ると、 Invoke-RestMethod
で各オプションを付ければ良い ことが推測できます。
CURLで指定したオプションは以下のようにマッピング出来そうですね。
- –requestは-Method
-Method Post
- –urlは-Uri
-Uri https://$domain/oauth/token
- –headerはHeadersとContentTypeが両方ありますね、ContentTypeだけ指定するので-ContentTypeのみ使います(Headersにcontent-typeと入れたらエラーになってました)
-ContentType application/json
- –dataは-body
- 後述しますがいい感じに書かないとNGでした
これで、bodyに当たる部分以外は良い感じにマッピング出来ました。
続いてはbodyの記載方法を見ます。
![](/images/20221130a/image.png)
ぱっと見は理解することが難しいですよね。オブジェクトで渡せば良いのかな? とわかります。
公式にPOSTの例があるので参考にできます。
$Cred = Get-Credential |
どうやらシェル内でオブジェクトを作れば良さそうだとわかります。この例を参考に以下のように動かすと エラーになります。
$body = @{ |
Invoke-RestMethod : invalid json |
理由ですが、bodyにjson渡す渡す詐欺(コンテンツタイプでJSON渡すと宣言してるがJSONを渡していない状態)をしてるようです。よしなにやってくれると少し期待しましたが、ダメなようです。
(※もし、何かしらの手法があれば教えてください)
対応方法
auth0 invoke rest method post body json powershell
といったキーワードで探すと、こちらの記事に記載している通り、 ConvertTo-Json
コマンドを用いbodyのオブジェクトをJSONに変換すれば良いということがわかります(-Body $body
➔ -Body ($body|ConvertTo-Json)
)。
※公式ドキュメントの関連記事の箇所にも ConvertTo-Json
の記載がありますが、本文にも記載があると助かる人もいるかなと思い、公式ドキュメントにフィードバックは出しておきました。これが採用されると嬉しいなと思います。
結果として、以下のコマンドで動きます。
$body = @{ |
しかし、少し斜め上な結果になります。
![1.png](/images/20221130a/1.png)
出力結果最後まで出ない問題
PowerShellの仕様か、Invoke-RestMethodの仕様なのか、出力が最後まで出てくれずトークンが分からない問題 が発生しました。
解決策として、公式の例を真似てファイルに出力して表示することにします(愚直にoutput.txt
に出してcat output.txt
します)。シェルに詳しい人だったら良い感じにCLIの出力出来たかもしれないですが、詳しい方は教えてください。
そのため、以下のコマンドを付けます。
... -OutFile output.txt |
総ユーザー数取得APIを打つ
最初に、Auth0全ユーザー数の取得コマンドを探すため、公式で用意されているAuth0 User Management APIのドキュメントを見ます。
そうすると、Users
➔ List or Search Users
の箇所のパラメータを眺めてると 小さく取得できる旨が書いて あります。APIの概要にはページング番号を指定しながらのユーザー取得しかできないかのように書いてあるが、よくよくパラメータを見ると取得できることがわかります。
API概要:1ページに取得されるユーザー数を指定してユーザーリストを取得できるんやでと記載されています。
Retrieve details of users. It is possible to: |
パラメータ:include_totalsをオンにするとAPIのレスポンスにトータルを含められると書いています。
include_totals |
しかし、この説明文だと、表示するページの合計なのか、全体なのか曖昧ですよね。
![image.png](/images/20221130a/image_2.png)
また、概要にある通りユーザーのリストが取得できてしまうが、合計人数だけ知りたいのでユーザー情報をなくすオプションを探します。※全パラメータは任意
パラメータ | 説明 |
---|---|
page | 返却するページ番号(0インデックス) |
per_page | 1ページに含むユーザー数、空の場合全件返却 |
include_totals | レスポンスに合計人数を入れる |
sort | ソート項目・順を決める |
connection | コネクションフィルター(よく分からず) |
fields | 表示/非表示する項目を決める。空の場合全項目返却 |
include_fields | fieldsで指定した項目を表示させるか非表示にするか決める |
q | 検索クエリ、形式はLucene query string syntaxらしい |
search_engine | サーチエンジンを決める、詳細はなかったため謎 |
per_page
に着目するとinclude_totals
だけ指定してper_page
を空にした場合全ユーザー情報が取得できてしまうようです。そしてユーザー取得フラグのようなものはなく、 per_page
をいじるしかなさそう なので、一旦これを0にしてAPIを実行することにします。
token取得時と同様に、まず成功するcurlコマンドを共有します。401認証失敗エラーにならないようにtokenをつけます。
curl --request GET \ |
観察・マッピング
クエリパラメータはGETなのでシンプルですね。token渡したGETリクエストするだけです。公式ドキュメントのリンクはこちらです。
- GETリクエストをしている
--request GET
が--Method Get
になる
- URLにPOSTと違いクエリパラメータがある
--url
が-Uri
になる-Uri https://$domain/api/v2/users?per_page=0&include_totals=true
- URLにパラメータを入れることをクエリパラメータと言う
- token認証情報を渡している
--header
が-Headers
になる-Headers @{Authorization="Bearer $token"}
- cURLと違い
Invoke-RestMethod
特有のオブジェクト形式で書かないといけないので@{xxx}の形式となる - Authenticationオプションなどでも指定可能だったかもしれない(未検証)
以上からInvokeコマンドに書き換えます。
Invoke-RestMethod -Method Get -Uri "https://$domain/api/v2/users?per_page=0&include_totals=true" -Headers @{Authorization="Bearer $token"} |
start : 0 |
無事totalの数字が取得できました!
最後に
curlコマンドの代替として、PowerShell標準の Invoke-webRequest
だったりInvoke-RestMethod
を用いてAuth0のAPIを操作する例をまとめました。
IT初心者がIT課題をどう解決していけば良いのか何となく分かるような文章を書けたら良いなと最近考えているため、ハマった部分や調査の流れもなるべく残すように記載しました。ググっても情報が見つかりにくかったことを記事にして誰かを助ける備忘録にもなってたら良いなと思います。
この記事が良いなと思ったら感想下さると励みになります。Twitterなどでコメントいただけると幸いです。