PowerShell Invoke-RestMethod로 JSON POST 요청하기

PowerShell에서 JSON을 POST하려면 본문을 해시테이블로 만들고([ordered]@{}를 쓰면 키 순서가 유지됩니다) ConvertTo-Json -Depth 10으로 변환한 다음, -Headers에 Authorization: Bearer 헤더를 넣어 Invoke-RestMethod -Method Post -ContentType 'application/json' -Body $json으로 보내세요. -ContentType을 빼면 POST가 application/x-www-form-urlencoded로 전송되고, -Depth를 빼면 ConvertTo-Json은 중첩 객체를 두 단계까지만 포함합니다.

PowerShell 관련 내용은 Microsoft Learn의 PowerShell 7.5용 Invoke-RestMethod와 ConvertTo-Json 페이지, 그리고 출처에 나열한 Windows PowerShell 5.1 페이지에서, Sume 관련 내용은 Format 호출하기 (영문), 오류와 비용 (영문), 인증에서 가져왔습니다. 모두 2026-09-28에 확인했습니다. Sume에는 PowerShell 모듈이 없으며, 여기서는 HTTPS를 직접 호출합니다.

Invoke-RestMethod로 JSON 본문을 어떻게 POST하나요?

아래 PowerShell 7 스크립트는 Sume Format 실행을 시작합니다. 본문이 input 안에 product를 중첩하므로 -Depth가 중요합니다. Sume 자체의 생성 예제는 output_schema 안에 JSON Schema를 넣어 더 깊이 들어갑니다. -Depth는 최대 100까지 받으며, PowerShell 7.1 이상은 입력이 설정한 값보다 깊으면 경고를 표시합니다. Invoke-RestMethod는 JSON 응답을 객체로 바꾸므로 $run.data.id가 실행의 ID입니다.

[ordered]는 키를 작성한 순서대로 유지합니다. Microsoft의 about_Hash_Tables 페이지에 따르면 일반 해시테이블의 키 순서는 결정적이지 않습니다. 이 점은 다시 보낼 때 중요합니다. 현재 코드에서 Sume는 재전송된 input을 키가 전송된 순서 그대로 비교하므로, 같은 데이터라도 순서가 다르면 다른 본문으로 봅니다.

$json = [ordered]@{
  instruction   = 'Make the weekly promo video.'
  input         = [ordered]@{ product = [ordered]@{ name = 'Trail mug'; sku = 'MUG-01' } }
  communication = @{ webhook_url = 'https://example.com/hooks/sume' }
} | ConvertTo-Json -Depth 10

$headers = @{
  Authorization     = "Bearer $env:SUME_API_KEY"
  'Idempotency-Key' = 'weekly-promo-2026-w40'
}

$run = Invoke-RestMethod -Uri 'https://api.sume.com/v1/formats/acme/weekly-promo/runs' `
  -Method Post -ContentType 'application/json' -Headers $headers -Body $json `
  -TimeoutSec 30 -SkipHttpErrorCheck -StatusCodeVariable status

if ($status -ge 400) { throw "Sume $status $($run.error.code): $($run.error.message)" }
$run.data.id  # 202: new run. 200: replay of the same key and body.

Invoke-RestMethod로 Bearer 토큰은 어떻게 보내나요?

-Headers는 해시테이블을 받으므로 @{ Authorization = "Bearer $env:SUME_API_KEY" }는 모든 버전에서 동작합니다. PowerShell 6.0 이상에는 -Authentication Bearer도 있는데, 이 옵션은 -Token을 SecureString으로 요구하며 -Headers로 넘긴 Authorization 헤더를 모두 덮어씁니다. Windows PowerShell 5.1에는 -Authentication 매개변수가 없습니다.

• Sume는 Authorization: Bearer나 x-api-key 중 하나를 받으며, 둘 다 받지는 않습니다. 둘을 함께 실은 요청은 Send only one API key credential. 메시지와 함께 401 unauthorized가 됩니다.
• 키는 커밋되는 스크립트가 아니라 환경 변수나 시크릿 저장소에 두세요. Sume 문서는 API 키를 신뢰할 수 있는 서버, CI 시크릿 저장소, 개발자 머신에 두도록 안내합니다.
• -TimeoutSec을 설정하세요. 기본값 0은 무기한 기다립니다.
• Windows PowerShell 5.1에서 curl은 Invoke-WebRequest의 별칭이므로, API 문서에서 복사한 curl 명령을 그곳에서 실행하면 curl이 실행되지 않습니다.

예외 대신 API의 JSON 오류를 어떻게 읽나요?

PowerShell 7에서 -SkipHttpErrorCheck를 쓰면 cmdlet이 HTTP 오류 상태를 무시하고 오류 응답을 성공한 것처럼 파이프라인에 기록하며, -StatusCodeVariable은 상태 코드를 저장합니다. 위 스크립트는 이 둘로 Sume의 오류 봉투(code, message, request_id, retryable, next_action)를 읽습니다. Windows PowerShell 5.1에는 두 매개변수가 모두 없으므로, 그곳에서는 try/catch로 오류를 잡으세요. 생성 단계의 4xx는 아무것도 실행되지 않았고 아무것도 청구되지 않았다는 뜻이므로, 재시도하지 말고 호출을 고치세요.

POST에 -MaximumRetryCount를 써도 되나요?

멱등성 키 없이는 쓰지 마세요. -MaximumRetryCount는 상태 코드가 400에서 599 사이이거나 304일 때마다 재시도하므로, 성공할 수 없는 400이나 401도 다시 보내고 유료 생성 요청도 다시 보냅니다. 대기 시간은 -RetryIntervalSec으로 정하며, Retry-After가 있는 429를 받으면 cmdlet은 대신 그 시간만큼 기다립니다. Windows PowerShell 5.1에는 두 매개변수가 모두 없습니다. Sume 문서는 안전하지 않은 제출 요청을 Idempotency-Key 없이 재시도하지 말라고 안내합니다. 키가 있으면 다시 보내도 안전합니다.

• 같은 키, 같은 본문: 원래 실행과 idempotency_hit: true가 담긴 200이 돌아옵니다. 두 번째 실행도, 두 번째 청구도 없습니다.
• 첫 요청이 아직 처리 중일 때 같은 키: 409 idempotency_key_in_use가 돌아오며, 약 일 초 뒤에 재시도할 수 있습니다.
• 키는 호출마다 새로 만든 GUID가 아니라 주차처럼 만들고 있는 대상에서 유도하세요. Sume 문서는 요청마다 무작위 키를 쓰면 헤더가 장식에 그친다고 말합니다. 키 설계는 AI 영상 API 멱등성 키에서 다룹니다.