Axe Developer Hub APIで始めよう

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

認証を設定し、プロジェクトIDを見つけ、Axe Developer Hub REST APIへの最初のコールを行います

Not for use with personal data

すべてのAxe Developer Hub APIは同じセットアップを使用します：リクエストヘッダーで送信されるAxeアカウントAPIキーと、ほとんどのリクエストで必要なプロジェクトIDです。このガイドはそのセットアップを一度行い、動作確認のための最初のコールを行い、その後、あなたが考えているタスクのためのAPIを紹介します。

note

個別のAPI認証情報はありません。 あなたがAxe Developer Hubにテスト結果を送信するためにすでに使用しているAxeアカウントAPIキーは、すべてのAxe Developer Hub APIでも使用可能です。

APIキーの取得

Axeアカウントポータルにサインインします。
あなたのプロジェクトが使用する製品のAPIキーをコピーします：
- ウェブおよびCI/CDプロジェクト向けのAxe Developer Hub APIキー。
- モバイルプロジェクト向けのAxe DevTools Mobile APIキー。

APIキーはその製品専用のデータのみを返します。Axe Developer Hub APIキーでAxe DevTools Mobileデータを取得することはできず、Axe DevTools Mobile APIキーでAxe Developer Hubデータを取得することもできません。たとえ組織管理者であっても同じです。キーがアクセスできるプロジェクトは、プロジェクトメンバーシップと役割に依存します：セッションと結果 API リファレンスおよびプロジェクト API リファレンスのアクセス制御をご確認ください。

各リクエストにAPIキーを送信する

すべてのリクエストのX-API-KeyヘッダーにAPIキーを送信し、AcceptヘッダーでJSONレスポンスを要求します：

X-API-Key: <DEQUE_API_KEY>
Accept: application/json

APIキーは秘密として扱い、環境変数やCI/CDプラットフォームのシークレットストアに保存し、リクエストにハードコーディングしないでください。このガイドの例はAPI_KEY環境変数から読み取ります。

プロジェクトIDを見つける

ほとんどのリクエストはプロジェクトIDでプロジェクトを識別します。これを見つける方法は2つあります：

Axe Developer Hub内：あなたのプロジェクトに移動し、プロジェクトの設定メニューを開いてプロジェクトの設定を選択します。プロジェクトIDは手順ページの上部に表示されます。
プロジェクト API で：プロジェクトの名前からIDを検索します。プロジェクトIDを名前で検索するを参照。

最初のコールを行う

あなたのAPIキーがアクセスできるプロジェクトを一覧表示します。このリクエストにはプロジェクトIDは不要であるため、キーが機能していることを迅速に確認する方法です：

curl -s \
  -H "Accept: application/json" \
  -H "X-API-Key: $API_KEY" \
  "https://axe.deque.com/api-pub/v1/results/projects"

JSON形式のプロジェクト配列を含む200 OK応答が、あなたのキーが有効かつアクティブであることを意味します。各プロジェクトのproject_idが他のAPIで使用するIDです。代わりに401 Unauthorizedを受け取った場合は、キーの全体をコピーしたことを確認し、プロジェクトが使用する製品に属しているか確認してください。

タスクを選択する

CI/CDパイプラインをゲートする

コミットステータス APIを使用して、アクセシビリティエラーが見つかった場合にプルリクエストまたはコミットを失敗させます。リクエストにはGitコミットSHAとプロジェクトIDを渡し、レスポンスにはそのコミットのテスト実行からのアクセシビリティエラーの数と、その中であなたのアクセシビリティしきい値を超えた数が報告されます。あなたのプロジェクトはGitデータを使用する必要があります。

パイプラインがGitHub上で動作している場合は、APIを直接呼び出す代わりにGitHubアクションを使用するを使用します。

アクセシビリティ結果を取得する

セッションと結果 APIを使用して結果をダウンロードします。セッションエンドポイントを呼び出してプロジェクトのセッションを一覧表示し、そのセッションのsession_idを結果エンドポイントに渡します。

結果エンドポイントの2つの動作が、クライアントの書き方に影響します：

結果の準備には時間がかかることがあります。 204 No Content応答は結果がまだ準備されていないことを意味します。少し待ってリクエストを繰り返し、200 OKを受け取るまで続けます。セッション状態とポーリングパターンを参照。
Brotli圧縮で結果が最も速くダウンロードされます。 Accept-Encoding: br を送信する（もしくは curl --compressed を使用してBrotli対応curlを使用する）、特にformat=fullの場合に。応答圧縮を参照。

プロジェクトとメンバーを管理する

プロジェクトを一覧表示したり、ページをめくったり、名前でプロジェクトIDを見つけたりするには、プロジェクト APIを使用してください。また、プロジェクトを作成、更新、削除したり、プロジェクトメンバーを追加、変更、または削除することもできます。それらの作業を自動化するには、プロジェクト管理自動化の開始を始めてください。

エラーと再試行の処理

Axe Developer Hub APIは、共通のエラーレスポンスセットを共有しています。

ステータス	意味	再試行？
`400 Bad Request`	パスやクエリパラメータ、またはリクエストボディが無効です。たとえば、不正なIDやタイムスタンプ、必須フィールドの不足などです。	いいえ。まずリクエストを修正してください。
`401 Unauthorized`	APIキーが無効または欠落しているか、サブスクリプションが非アクティブです。	いいえ。キーとサブスクリプションを確認してください。
`403 Forbidden`	APIキーがリクエストされたプロジェクトや操作にアクセスできません。たとえば、管理者でないプロジェクトを更新しようとする場合です。	いいえ。プロジェクトメンバーシップや役割を確認し、サブスクリプションがプロジェクトタイプをカバーしていることを確認してください。
`404 Not Found`	リクエストされたプロジェクト、セッション、またはコミットが存在しません。	いいえ。IDまたはSHAを確認してください。
`429 Too Many Requests`	システムが高負荷状態です。	はい、`Retry-After`ヘッダーに指定された秒数後に再試行してください。

結果エンドポイントをポーリングするとき、204 No Contentはエラーではありません。それは結果がまだ準備できていないことを意味し、短時間待ってから同じリクエストを再試行します。再試行回数が増えるほど、待ち時間を長くし、一定の制限を超えた場合、セッションが停止してパイプラインを無期限にブロックしないようにすることが必要です。

各リファレンスページには、そのエンドポイントに対する正確なエラーレスポンスがリストされています。再試行ロジックを構築して、結果エンドポイントだけでなく、あらゆるエンドポイントからの429 Too Many Requestsを処理できるようにしてください。