Skip to Content
リファレンスアクションHTTP

HTTPアクション

httpアクションはHTTPリクエストを実行し、レスポンスをアサーションやoutputsから参照できるようにします。

基本的な構文

steps:
  - name: Check the API
    uses: http
    with:
      url: "https://api.example.com/health"
      method: GET
    test: res.code == 200

パラメータ

パラメータ型必須デフォルト説明
urlString必須-リクエストURL。メソッド省略記法でパスを渡す場合はベースURL
methodString必須-HTTPメソッド。メソッド省略記法を使う場合はそちらが設定します
headersObject任意-リクエストヘッダー
bodyStringまたはObject任意-リクエストボディ。content-typeがapplication/jsonのとき、オブジェクトはJSONにシリアライズされます
timeoutDuration任意30sレスポンスの読み取りまで含めた、リクエスト全体の制限時間

リダイレクトとTLS検証を指定するパラメータはありません。リダイレクトは既定で追跡します。

timeout

timeoutには10sや1m30sのようなduration文字列、または秒数の数値を指定します。0を指定すると制限しません。

  - name: Slow endpoint
    uses: http
    with:
      url: "{{vars.api_url}}/report"
      method: GET
      timeout: 60s
    test: res.code == 200

制限時間を超えたリクエストはClient.Timeout exceededのエラーになり、ステップは失敗します。

ジョブのdefaultsでまとめて指定できます。

jobs:
  - name: API checks
    defaults:
      http:
        timeout: 5s
    steps:
      - name: Health
        uses: http
        with:
          get: /health
        test: res.code == 200

ステップのtimeoutはこれとは別の、アクション実行1回ごとの外側の制限です（既定5分）。with.timeoutがHTTPリクエストそのものを、ステップのtimeoutがそれを包むアクション呼び出しを区切ります。応答を返さないまま固まったアクションを止めるのは後者です。

メソッド省略記法

get head post put patch delete connect options traceは、メソッドとパスを1つのキーで指定します。値は完全なURLか、urlからの相対パスです。ジョブのdefaultsと組み合わせると簡潔に書けます。

jobs:
  - name: API checks
    defaults:
      http:
        url: "{{vars.api_url}}"
        headers:
          accept: application/json
    steps:
      - name: List users
        uses: http
        with:
          get: /users
        test: res.code == 200
 
      - name: Create a user
        uses: http
        with:
          post: /users
          headers:
            content-type: application/json
          body:
            name: "{{vars.user_name}}"
        test: res.code == 201

レスポンスオブジェクト

フィールド型説明
res.codeIntegerステータスコード（例: 200）
res.statusStringステータス行（例: "200 OK"）
res.headersObjectレスポンスヘッダー。キーはContent-Typeのような正規形
res.bodyAnyレスポンスボディ。JSONならオブジェクトや配列に解析され、それ以外は文字列
res.rawbodyString解析前のボディ。JSONとして解析したときに入ります
res.filepathStringバイナリレスポンスを保存したファイルのパス
rt.durationStringラウンドトリップ時間（例: "120ms"）
rt.secFloatラウンドトリップ時間（秒）
statusIntegerステータスコードが2xxなら0、それ以外は1

レスポンス例

JSONレスポンスの値はres.bodyから直接読みます。

    test: |
      res.code == 200 &&
      res.headers["Content-Type"] contains "application/json" &&
      res.body.status == "ok" &&
      len(res.body.items) > 0
    outputs:
      first_id: res.body.items[0].id
      elapsed_ms: rt.sec * 1000

テキストやHTMLのレスポンスでは、res.bodyは文字列そのものです。

    test: |
      res.code == 200 &&
      res.body contains "<title>" &&
      len(res.body) > 100

一般的なパターン

認証

  - name: Log in
    id: auth
    uses: http
    with:
      url: "{{vars.api_url}}/login"
      method: POST
      headers:
        content-type: application/json
      body:
        user: "{{vars.user}}"
        password: "{{vars.password}}"
    test: res.code == 200
    outputs:
      token: res.body.access_token
 
  - name: Call a protected endpoint
    uses: http
    with:
      url: "{{vars.api_url}}/me"
      method: GET
      headers:
        authorization: "Bearer {{outputs.auth.token}}"
    test: res.code == 200

Basic認証はencode_base64で組み立てます。

      headers:
        authorization: "Basic {{encode_base64(vars.user + ':' + vars.password)}}"

エラーレスポンスの検証

  - name: Unknown id returns 404
    uses: http
    with:
      url: "{{vars.api_url}}/users/does-not-exist"
      method: GET
    test: res.code == 404 && res.body.error != null

不安定なエンドポイントのリトライ

  - name: Eventually consistent read
    uses: http
    retry:
      max_attempts: 5
      interval: 2s
    with:
      url: "{{vars.api_url}}/orders/{{outputs.create.order_id}}"
      method: GET
    test: res.code == 200

関連項目

更新日時
変数SMTP