知識マップ: PowerShellでREST APIと連携する ── Invoke-RestMethodの実務
記事「PowerShellでREST APIと連携する ── Invoke-RestMethodの実務」の主張を、概念と関係(エッジ)に分解した知識グラフの全体です。各関係には根拠・確認日・確度が付いています。
この記事は、PowerShellからJSON APIを呼ぶ実務をInvoke-RestMethodを中心に整理する。ConvertTo-Jsonは既定の深さが2であるため入れ子の切り捨てを招きやすく、日本語の文字化けはUTF-8のバイト配列に変換してから送るのが確実だとしている。4xx/5xxは終了エラーになりエラー本文の確認が調査の鍵になるとしつつ、-MaximumRetryCountの組み込み再試行は400から599までを対象にするため、401や404のような恒久的エラーまで再送してしまう点を指摘し、コード別の扱いや指数バックオフ、POSTのような非冪等な要求を再送しない判断が必要な場面では自前のリトライ関数を推奨している。Windows PowerShell 5.1ではTLS 1.2の明示や-SkipHttpErrorCheck・-Authenticationの非対応が壁になり、恒久運用では-SkipCertificateCheckで証明書検証を無効化せず社内CAを信頼させるべきだとしている。
flowchart LR
accTitle: PowerShellによるREST API連携の知識マップ
accDescr: Invoke-RestMethodを中心に、JSON送受信の文字化けと入れ子切り捨て対策、エラー処理、429の組み込み再試行と自前の指数バックオフ・冪等性判定、ページング、Windows PowerShell 5.1固有の非互換、プロキシと証明書の扱いが結びつく関係を示す図。
invoke_restmethod["Invoke-RestMethod"]
rest_api["REST API"]
powershell["PowerShell"]
invoke_webrequest["Invoke-WebRequest"]
convertto_json["ConvertTo-Json"]
json_depth_truncation["JSONの入れ子の切り捨て"]
json_mojibake["JSON送受信時の文字化け"]
utf8_byte_encoding["UTF-8バイト配列化"]
skiphttperrorcheck_parameter["-SkipHttpErrorCheckパラメーター"]
maximumretrycount_parameter["-MaximumRetryCount / -RetryIntervalSecパラメーター"]
retry_after_header["Retry-Afterヘッダー"]
permanent_http_error["恒久的なHTTPエラー(401/403/404など)"]
custom_retry_function["自前のリトライ関数(Invoke-KsApiパターン)"]
exponential_backoff["指数バックオフ"]
http_idempotency["HTTPメソッドの冪等性"]
cursor_pagination["カーソル/オフセット方式のページング"]
followrellink_parameter["-FollowRelLinkパラメーター"]
proxy_configuration["プロキシ構成(-Proxy / -ProxyCredential / -NoProxy)"]
windows_powershell_5_1["Windows PowerShell 5.1"]
tls_1_2["TLS 1.2の明示的な有効化"]
authentication_parameter["-Authenticationパラメーター"]
client_certificate["クライアント証明書"]
skipcertificatecheck_parameter["-SkipCertificateCheckパラメーター"]
powershell -->|"利用する"| invoke_restmethod
powershell -.->|"利用する"| invoke_webrequest
invoke_restmethod -->|"利用する"| convertto_json
convertto_json -->|"原因になり得る"| json_depth_truncation
invoke_restmethod -.->|"原因になり得る"| json_mojibake
utf8_byte_encoding -->|"推奨される対応"| json_mojibake
invoke_restmethod -->|"利用する"| skiphttperrorcheck_parameter
invoke_restmethod -->|"利用する"| maximumretrycount_parameter
maximumretrycount_parameter -->|"利用する"| retry_after_header
maximumretrycount_parameter -->|"用いるのは非推奨"| permanent_http_error
custom_retry_function -->|"利用する"| exponential_backoff
custom_retry_function -->|"利用する"| retry_after_header
custom_retry_function -->|"前提とする"| http_idempotency
custom_retry_function -->|"推奨される対応"| permanent_http_error
cursor_pagination -.->|"利用する"| custom_retry_function
invoke_restmethod -->|"利用する"| followrellink_parameter
invoke_restmethod -->|"で構成できる"| proxy_configuration
windows_powershell_5_1 -.->|"前提とする"| tls_1_2
windows_powershell_5_1 -->|"両立しない"| skiphttperrorcheck_parameter
windows_powershell_5_1 -->|"両立しない"| authentication_parameter
invoke_restmethod -.->|"利用する"| authentication_parameter
invoke_restmethod -->|"利用する"| client_certificate
invoke_restmethod -->|"利用する"| skipcertificatecheck_parameter
skipcertificatecheck_parameter -->|"用いるのは非推奨"| rest_api
概念間の関係(全24件)
図と同じ関係を文章でも列挙します。表示している文と機械可読な意味データ(RDFa)は同じ要素に載っています。確度が「確立した関係」のものは直接の関係として、「条件付きの関係」のものは成立条件つきの言明(rdf:Statement)として表現しています。
- PowerShellはInvoke-RestMethodを利用します。
- PowerShellはInvoke-WebRequestを利用します。
- Invoke-RestMethodはConvertTo-Jsonを利用します。
- ConvertTo-JsonはJSONの入れ子の切り捨ての原因になることがあります。
- Invoke-RestMethodはJSON送受信時の文字化けの原因になることがあります。
- UTF-8バイト配列化はJSON送受信時の文字化けに対する本記事の推奨です。
- Invoke-RestMethodは-SkipHttpErrorCheckパラメーターを利用します。
- Invoke-RestMethodは-MaximumRetryCount / -RetryIntervalSecパラメーターを利用します。
- -MaximumRetryCount / -RetryIntervalSecパラメーターはRetry-Afterヘッダーを利用します。
- -MaximumRetryCount / -RetryIntervalSecパラメーターを恒久的なHTTPエラー(401/403/404など)に用いることは推奨されません。
- 自前のリトライ関数(Invoke-KsApiパターン)は指数バックオフを利用します。
- 自前のリトライ関数(Invoke-KsApiパターン)はRetry-Afterヘッダーを利用します。
- 自前のリトライ関数(Invoke-KsApiパターン)はHTTPメソッドの冪等性を前提とします。
- 自前のリトライ関数(Invoke-KsApiパターン)は恒久的なHTTPエラー(401/403/404など)に対する本記事の推奨です。
- カーソル/オフセット方式のページングは自前のリトライ関数(Invoke-KsApiパターン)を利用します。
- Invoke-RestMethodは-FollowRelLinkパラメーターを利用します。
- Invoke-RestMethodはプロキシ構成(-Proxy / -ProxyCredential / -NoProxy)で構成できます。
- Windows PowerShell 5.1はTLS 1.2の明示的な有効化を前提とします。
- Windows PowerShell 5.1は-SkipHttpErrorCheckパラメーターと両立しません。
- Windows PowerShell 5.1は-Authenticationパラメーターと両立しません。
- Invoke-RestMethodは-Authenticationパラメーターを利用します。
- Invoke-RestMethodはクライアント証明書を利用します。
- Invoke-RestMethodは-SkipCertificateCheckパラメーターを利用します。
- -SkipCertificateCheckパラメーターをREST APIに用いることは推奨されません。
主要概念の定義
機械可読データ
このページはサイトの知識グラフ(_data/knowledge/)から自動生成されています。誤りの指摘はお問い合わせからお願いします。