プログラムで結果を取得

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

RESTサービスを使用して、シンプルなGETインターフェースを通じてアクセシビリティ結果のサマリーレポートをダウンロードする

Not for use with personal data
important

このエンドポイントは非推奨です。 新しいセッションと結果APIを使用してください。このエンドポイントからのレスポンスにはDeprecation レスポンスヘッダーが含まれています。

セッションと結果APIへの移行

この新しいセッションと結果APIは、このエンドポイントを2つの別々のエンドポイントで置き換えます。1つはプロジェクトのセッションを一覧表示するもので、もう1つは特定のセッションの結果を取得するものです。この2ステップモデルでは、最新のものだけでなく、ブランチやコミット全体のすべてのセッションにアクセスできます。

format=summaryを使用した同等のリクエスト

結果エンドポイントのformat=summaryモードは、このエンドポイントと同じJSON形式を返します。既存のリクエストを再現するには、まずブランチやコミットに一致するセッションを見つけ、その結果をリクエストします。

  1. セッションを一覧表示 を使用して、関心のあるブランチまたはコミットのsession_id を見つけるために、git_branch またはcommit_sha フィルターを使用します。

    curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
      "https://axe.deque.com/api-pub/v1/results/projects/$PROJECT_ID/sessions?git_branch=$GIT_BRANCH"
  2. 結果をリクエスト そのセッションのsession_idを行い、このエンドポイントと同じJSON形式を使用したformat=summaryを行います。

    curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
      "https://axe.deque.com/api-pub/v1/results/sessions/$SESSION_ID/results?format=summary"
    important

    新しいエンドポイントは結果が生成されている間204 No Contentを返し、このエンドポイントのようにはではない 202 Processingしません。既存のコードが202レスポンスをチェックする場合、204を処理するように更新してください。完全なポーリング例についてはセッションの状態とポーリングパターンを参照してください。

format=fullを使用したさらなる活用

サマリーが提供するもの以上の完全な問題レベルの詳細が必要な場合は、format=fullを使用してユニバーサルJSON(共通エクスポート形式)で結果を取得してください。この形式は、セッション中に見つかったすべてのアクセシビリティの問題を含みます:個別の違反、不完全なチェック、合格、適用外のルールがページごとに整理されています。

curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
  "https://axe.deque.com/api-pub/v1/results/sessions/$SESSION_ID/results?format=full"

レガシーエンドポイントリファレンス

ダウンロード可能なレポートRESTサービスを使用して、簡単な処理や他のソフトウェアへのインポートのために、Axe Developer Hubのアクセシビリティ結果をJSONデータとしてダウンロードできます。GETサービスには、2つの必須パラメータがあります。

  • APIキー - あなたのプロジェクトに対応する個人のAPIキーをAxeアカウントポータルで見つけるか、新しいAPIキーを追加してください。プロジェクトがWeb API、CLI、またはWatcherを使用している場合はAxe Developer Hub APIキーを選択してください。モバイルプロジェクトの場合はAxe DevTools Mobile APIキーを使用してください。
  • プロジェクトID - ダウンロードしたいプロジェクトデータに対応するプロジェクトIDを提供してください。あなたのプロジェクトIDはAxe Developer Hubで見つけることができます。

2つのオプションのパラメータを使用して、クエリを特定のGitブランチまたは特定のGitコミットSHAに限定することができます。

リクエストサマリー

  • エンドポイント: https://axe.deque.com/api-pub/watcher/downloadable/report
  • リクエスト: GET
  • ヘッダー(必須):
    • X-API-Key: <DEQUE_API_KEY>
    • Accept: application/json
  • クエリパラメータ:
    • project_id (必須)
      • 説明: ダウンロードしたいプロジェクトのレポートのプロジェクトIDを指定します。このパラメータは必須です。
      • 使用例: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>
    • branch_name (任意)
      • 説明: 指定したGitブランチ名のダウンロード可能なレポートを返します。
      • 使用例: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&branch_name=<GIT_BRANCH>
    • commit_sha (任意)
      • 説明: 指定したGitコミットSHAのダウンロード可能なレポートを返します。
      • 使用例: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>
important

初回実行時には、ダウンロード可能なレポートが生成されているため202 Processing応答を受け取ることが予想されます。コードはこの応答を処理し、リクエストを再試行する必要があります。完全な例については以下の202処理応答の処理を参照してください。

curlリクエストの例

curl -L -H 'Accept: application/json' -H 'X-API-Key: <DEQUE_API_KEY>' 'https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>'
note

202 Processingの応答を受け取った場合は、リクエストを再試行してください。202応答を処理するための例のスクリプトについては202処理応答の処理を参照してください。

例の応答ボディ

{
  "report_id": "a4990926-3014-4799-aa39-7aca31fce412",
  "source": {
    "product_name": "axe-devtools-html",
    "product_component_name": "axe-devtools-watcher",
    "product_version": "3.20.2"
  },
  "test_details": {
    "test_id": "da0c79a5-6f1e-4692-a255-5757629208fa",
    "start_date": "2025-05-05T20:02:31.883Z",
    "end_date": "2025-05-05T20:02:42.789Z"
  },
  "commit": {
    "sha": "f73ea5a02386b359ffa79a76473f7a5ad41759d5",
    "author": "John Doe",
    "author_email": "john.doe@example.com",
    "message": "Merge pull request #233 from deque/221-add-examples-for-using-global-config-fields-2",
    "branch_name": "main",
    "repository_url": "https://github.com/dequelabs/watcher-examples.git",
    "tag": null
  },
  "devhub_summary": {
    "issue_count_total": 17,
    "issue_count_by_impact": {
      "critical": 0,
      "serious": 2,
      "moderate": 15,
      "minor": 0
    },
    "issue_count_by_rule": [
      {
        "severity": "serious",
        "rule_id": "color-contrast",
        "rule_help": "Elements must meet minimum color contrast ratio thresholds",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/color-contrast?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "heading-order",
        "rule_help": "Heading levels should only increase by one",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/heading-order?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "landmark-one-main",
        "rule_help": "Document should have one main landmark",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/landmark-one-main?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "page-has-heading-one",
        "rule_help": "Page should contain a level-one heading",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/page-has-heading-one?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "region",
        "rule_help": "All page content should be contained by landmarks",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/region?application=axeAPI",
        "count": 9
      }
    ]
  }
}

応答オブジェクト

次のセクションでは、応答ボディ内のJSONオブジェクトについて説明します。

トップレベル構造

フィールド タイプ 説明
report_id 文字列 レポートの一意の識別子 (UUID形式)
source オブジェクト レポートのソースに関する情報
test_details オブジェクト テスト実行に関する詳細
commit オブジェクト テストに関連付けられたGitコミット情報
devhub_summary オブジェクト 検出されたアクセシビリティの問題の概要

sourceオブジェクト

レポートを生成した製品に関する情報を含む:

フィールド タイプ 説明
product_name 文字列 製品の名前 (例: „axe-devtools-html“)
product_component_name 文字列 製品内のコンポーネント名 (例: „axe-devtools-watcher“)
product_version 文字列 テストに使用されたコンポーネントのバージョン

test_detailsオブジェクト

テスト実行に関する情報を含む:

フィールド タイプ 説明
test_id 文字列 テストの一意の識別子 (UUID形式)
start_date 文字列 テスト開始日時 (ISO 8601形式)
end_date 文字列 テスト完了日時 (ISO 8601形式)

commitオブジェクト

テストに関連付けられたGitコミットに関する情報を含む:

フィールド タイプ 説明
sha 文字列 GitコミットのフルSHAハッシュ
author 文字列 コミット著者のユーザー名
author_email 文字列 コミット著者のメールアドレス
message 文字列 コミットメッセージ
branch_name 文字列 コミットが行われたブランチの名前
repository_url 文字列 GitリポジトリのURL
tag 文字列またはnull コミットに関連付けられたGitタグがある場合

devhub_summaryオブジェクト

検出されたアクセシビリティの問題の概要情報を含む:

フィールド タイプ 説明
issue_count_total 数値 検出されたアクセシビリティの問題の総数
issue_count_by_impact オブジェクト 影響レベル別の問題の内訳
issue_count_by_rule 配列 ルール別に整理された問題のリスト
issue_count_by_impactオブジェクト

問題を影響レベル別に分類:

フィールド タイプ 説明
critical 数値 重大な影響のある問題の数
serious 数値 深刻な影響のある問題の数
moderate 数値 中程度の影響のある問題の数
minor 数値 軽微な影響のある問題の数
issue_count_by_rule配列

この配列の各オブジェクトは、次の構造を持つルールを表します:

フィールド タイプ 説明
severity 文字列 ルールの重大度レベル ("重大", "深刻", "中程度", "軽微")
rule_id 文字列 ルールの識別子
rule_help 文字列 ルールの簡単な説明
rule_help_url 文字列 ルールに関するDeque Universityのドキュメントへのリンク
count 数値 このルールに対して発見された問題の数

追加の応答

202 Processing

この応答は、レポートがまだ生成中であり、待機した後リクエストを再試行する必要があることを示しています。

レスポンスボディ

{
  "message": "Report is still processing",
  "state": "PROCESSING"
}

429 Too Many Requests

高負荷時には、このエンドポイントは429 Too Many Requestsを返すことがあり、すぐに処理を開始しない場合があります。基になる作業はキューに保持されるため、再試行しても重複処理は発生しません。応答にはRetry-Afterというヘッダーが秒単位で含まれており、それだけ待ってから再試行してください。

レスポンスボディ

{
  "error": "Too many requests. Retry after the Retry-After interval."
}

400 Bad Request

commit_shaに供給された値はSHA-1値ではありません。

レスポンスボディ

{
  "error": "commit_sha must be a valid SHA-1 hash"
}

401 Unauthorized

次のいずれかのエラーメッセージが401 Unauthorized応答に付随します。

指定されたAPIキーが無効です

レスポンスボディ

{
  "error": "Invalid API key"
}

APIキーを含む必要なヘッダーがありません:

レスポンスボディ

{
  "error": "X-API-Key or Authorization header required"
}

404 Not Found

次のいずれかのエラーメッセージが404 Not Found応答に付随します。

commit_shaで使用されたSHA値が見つかりませんでした

このエラーは、このSHAに対するデータがAxe Developer Hubデータにないことを示しており、通常これによりテストスイートがこのGitコミットに対して実行されなかったことを意味します。このエラーは、存在しないブランチ名とともに返されるエラーと同じです。(次のエラーを参照してください。)

レスポンスボディ

{
  "error": "Session not found"
}

branch_nameに提供された値が存在しません

このエラー応答は、前のエラーと同じです(commit_shaクエリパラメータで提供されたSHAがAxe Developer Hubデータに存在しない場合)。

レスポンスボディ

{
  "error": "Session not found"
}

project_idに供給された値が存在しません

このエラー応答は、前述の404エラーと同じです。

レスポンスボディ

{
  "error": "Session not found"
}

202 Processing応答の処理

このデモシェルスクリプトは、202 Processing応答を受け取った場合にレポートを再要求するためにcurlを使用する方法を示します。テストスイートは多数のアクセシビリティ違反を見つける可能性があるため、システムはレポートがダウンロード可能になる前にすべての結果を処理するために追加の時間を必要とするかもしれません。以下の例を使用してスクリプトを作成し、結果が利用可能かどうかを継続的に再試行することをお勧めします。このスクリプトは、試行ごとに5秒の遅延を持たせて最大20回リクエストを再試行します。

このサンプルは、API_KEY環境変数がAPIキーに、PROJECT_IDがプロジェクトIDに設定されていることを必要とします。

tip

echoステートメントを削除し、stdoutをリダイレクトしてダウンロード可能なレポートを取得したい場合は考慮してください。

#!/bin/bash

URL="https://axe.deque.com/api-pub/watcher/downloadable/report"
MAX_ATTEMPTS=20
DELAY=5
TEMP_FILE=$(mktemp)

for ((i=1; i<=MAX_ATTEMPTS; i++)); do
    echo "Attempt $i..."
    
    # Get both status and response
    STATUS=$(curl -s -w '%{http_code}' -L -H "Accept: application/json" -H "X-API-Key: $API_KEY" -o "$TEMP_FILE" "$URL?project_id=$PROJECT_ID")
    
    case $STATUS in
        200)
            echo "Success!"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 0
            ;;
        202)
            echo "Still processing, waiting ${DELAY}s..."
            sleep $DELAY
            ;;
        *)
            echo "Error: HTTP $STATUS"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 1
            ;;
    esac
done

echo "Timeout after $MAX_ATTEMPTS attempts"
rm "$TEMP_FILE"
exit 1