Axe Developer HubをCI/CDプラットフォームに統合する

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard

Axe Developer HubのRESTウェブサービスを様々なGitプラットフォームで利用する

Not for use with personal data

必要条件:

  • あなたの Web プロジェクトは Git データを使用しています
  • Axe Developer Hub プロジェクト ID
  • Deque API キーはあなたのプロジェクトタイプに対応しています

概要

Axe Developer Hub は、GitLab や BitBucket などのサービスと CI/CD を統合するための基盤として使用できる REST Web サービスを提供しています。GitHub を使用している場合は、Axe Developer Hub GitHub Actionの使用をご覧ください。

REST サービスは、入力として Axe Developer Hub API キー、プロジェクト ID、および Git コミット SHA を期待しています。レスポンスオブジェクトには以下の内容が含まれます:

  • 最後のテスト実行中に見つかったアクセシビリティエラーの数
  • a11y 閾値を超えたアクセシビリティエラーの数
  • Axe Developer Hub で詳細な結果を指し示す URL

テスト実行情報の取得

Web サービスは GET リクエストに応答し、指定された Developer Hub プロジェクトの特定の Git コミット SHA に関する情報を取得できます。

GET https://axe.deque.com/api-pub/v1/axe-watcher/gh/<:SHA>?project_id=<your-project-id>

要件

リクエストには、1つのパスパラメータ、1つのクエリパラメータ、および2つのヘッダーが必要です。

  • サーバー: https://axe.deque.com
  • エンドポイント: /api-pub/v1/axe-watcher/gh/<*:SHA*>
  • クエリパラメータ: ?project_id=<your-project-id>
  • リクエストメソッド: GET

パスパラメータ: :SHA パラメータは、調べたい Git コミット SHA に置き換える必要があります。

クエリパラメータ: プロジェクトを作成した後に、指示ページに表示されるユニークなプロジェクト ID に「」を置き換えます。セットアップ後にこの情報を見つけるには、Axe Developer Hub のプロジェクトに移動します。プロジェクトを見つけ、その設定に移動し、プロジェクトの設定を選択して指示ページを開きます。

ヘッダー: 2つのヘッダーが必要です:

  • Accept: application/json
  • X-API-Key:<your-personal-api-key>

API キーは秘密として扱い、環境変数やあなたの CI/CD プラットフォームの秘密ストアに保存し、リクエストにハードコーディングしないでください。

リクエストの例:

GET https://axe.deque.com/api-pub/v1/axe-watcher/gh/9eabf5b536662000f79978c4d1b6e4eff5c8d785?project_id=268a7e7d-cb23-45a0-aa7d-6f35e3bed2c9

(ヘッダーは必要ですが表示しません。)

応答 JSON

以下は、サービスから返された例の JSON 応答本文を示しています:

{
  "project_name": "Main test suite",
  "issues_over_a11y_threshold": 2,
  "last_run_created_at": "2024-01-21T17:16:39.267Z",
  "last_run_violation_count": 2,
  "last_run_new_violation_count": 2,
  "last_run_resolved_violation_count": 0,
  "last_run_page_state_count": 2,
  "difference_in_page_states": 0,
  "axe_url": "/axe-watcher/projects/19f12525-bcbe-4b4f-9b12-76de4f375d9b/branches/test-updates/compare/353ec943-b957-4abc-8d3a-5deed182a304/9288e977-b81f-49d7-83de-010255baede4?settings_hash=bc8334022f94bb2d9f69447946df487f&issues_over_a11y_threshold=2"
}

次の表は、JSON 応答内の値についての情報を提供します:

項目 タイプ 説明
axe_url string Axe Developer Hub 上のこれらの結果の絶対パス
difference_in_page_states number 同じブランチ上の前のコミットと比較したページ状態の数値の差
issues_over_a11y_threshold number a11y 閾値を超えた問題のカウント
last_run_created_at string テスト実行のISO 8601形式、UTCタイムゾーン、ミリ秒単位の日時
last_run_new_violation_count number 新たなアクセシビリティエラーの数
last_run_page_state_count number ページ状態のカウント
last_run_resolved_violation_count number このブランチの前のコミット以降に解決されたアクセシビリティ問題の数
last_run_violation_count number アクセシビリティエラーの数
project_name string Axe Developer Hub のプロジェクトページに表示されるプロジェクト名

エラーレスポンス

ステータス 原因 レスポンスボディ
404 Not Found SHA が見つからない、またはそれに関連付けられたテスト実行が存在しない { "error": "No Git information found" }
401 Unauthorized 無効な API キー { "error": "Invalid API key" }

Axe Developer Hub は、セッションデータや結果をプログラム的に取得するための追加 REST エンドポイントを提供しています。セッションエンドポイント(プロジェクトのフィルタリングおよびカーソルページネーション付きのセッション一覧)と、結果エンドポイント(特定のセッションのサマリーまたは完全なユニバーサル JSON 結果を取得)について「セッションと結果の API リファレンス」を参照してください。

使用例

以下の例は、REST エンドポイントにアクセスする方法を示しています。各例では、必要なパラメーターを環境変数として設定する必要があります。

環境変数 説明
API_KEY プロジェクトタイプに対応する個人用 API キー(Axe アカウントページにあります)
PROJECT_ID あなたのプロジェクトのユニークな ID
GIT_SHA Axe Developer Hub 結果を取得したい Git コミット SHA

JavaScript (Node.js)

この例では、指定された SHA(GIT_SHA 環境変数)とプロジェクト ID の Axe Developer Hub 結果を要求します。新しいアクセシビリティエラーが発見された場合、その数がコンソールにログされます。それ以外の場合は、「axe clean!」がコンソールにログされます。

note

この例では、無効な API キーや Git 情報の欠如などのエラーをないテストしません。

const https = require('https')
const assert = require('assert')

const { API_KEY, PROJECT_ID, GIT_SHA } = process.env
assert(API_KEY, 'API_KEY is required')
assert(PROJECT_ID, 'PROJECT_ID is required')
assert(GIT_SHA, 'GIT_SHA is required')

const request = () =>
  new Promise((resolve, reject) => {
    /** @type {import('http').RequestOptions} */
    const options = {
      hostname: 'axe.deque.com',
      port: 443,
      path: `/api-pub/v1/axe-watcher/gh/${GIT_SHA}?project_id=${PROJECT_ID}`,
      method: 'GET',
      headers: {
        'X-API-Key': API_KEY,
        Accept: 'application/json'
      }
    }

    let data = ''

    const req = https.request(options, res => {
      res.on('error', reject)

      res.on('data', d => {
        data += d
      })

      res.on('end', () => {
        const json = JSON.parse(data)
        resolve(json)
      })
    })
    req.end()
  })

const main = async () => {
  let json = null
  for (let tries = 0; tries < 10; tries++) {
    try {
      json = await request()
      break
    } catch (err) {
      console.warn(err.message)
    }
  }

  assert(json, 'Unable to fetch data from axe.deque.com')

  const { last_run_violation_count, axe_url, project_name, issues_over_a11y_threshold } = json

  if (last_run_violation_count) {
    console.log(
      `There are ${last_run_violation_count} violations in ${project_name}!`
    )
    console.log(`See ${axe_url} for more information`)
  } else {
    console.log('axe clean!')
  }
}

main()

Bash

この例では、curlとjqを使用して標準出力に違反件数を出力します。

#!/bin/bash

if [ -z $API_KEY ] || [ -z $PROJECT_ID ] || [ -z $GIT_SHA ]; then
  echo "Must set the API_KEY, PROJECT_ID, and GIT_SHA environment variables."
  exit 1
fi

curl --fail -H "Accept: application/json" -H "X-API-Key: $API_KEY" "https://axe.deque.com/api-pub/v1/axe-watcher/gh/$GIT_SHA?project_id=$PROJECT_ID" | jq '.last_run_violation_count'

ウェブサービスがサーバーエラーを返した場合、curl --failはコード 22 で終了し、レスポンスボディを抑制します。レスポンス JSON も標準出力の一部として返すには、--fail-with-bodyオプションを使用してください。