Ergebnisse programmgesteuert erhalten

Der herunterladbare Berichte REST-Dienst ermöglicht es Ihnen, eine Zusammenfassung Ihrer Barrierefreiheitsergebnisse aus dem Axe Developer Hub als JSON-Daten herunterzuladen, um sie weiter zu verarbeiten oder in andere Software zu importieren. Der GET-Dienst hat zwei erforderliche Parameter:

• API-Schlüssel - Finden Sie einen persönlichen API-Schlüssel, der Ihrem Projekt entspricht, oder fügen Sie einen neuen API-Schlüssel im Axe Account Portalhinzu. Wählen Sie einen API-Schlüssel für den Axe Developer Hub, wenn Ihr Projekt die Web-APIs, CLI oder Watcher verwendet. Verwenden Sie einen Axe DevTools Mobile API-Schlüssel für mobile Projekte.
• Projekt-ID - Geben Sie die Projekt-ID für die entsprechenden Projektdaten an, die Sie herunterladen möchten. Finden Sie Ihre Projekt-ID im Axe Developer Hub.

Sie können zwei optionale Parameter verwenden, um Ihre Abfrage auf einen bestimmten Git-Branch oder einen bestimmten Git-Commit-SHAeinzuschränken.

Anforderungszusammenfassung

• Endpunkt: https://axe.deque.com/api-pub/watcher/downloadable/report
• Anforderung: GET
• Header (erforderlich):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Abfrageparameter:
  • project_id (Erforderlich)
    • Beschreibung: Gibt die Projekt-ID für den Bericht an, den Sie herunterladen möchten. Dieser Parameter ist erforderlich.
    • Beispielverwendung: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>
  • branch_name (Optional)
    • Beschreibung: Gibt den herunterladbaren Bericht für den angegebenen Git-Branch-Namen zurück.
    • Beispielverwendung: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&branch_name=<GIT_BRANCH>
  • commit_sha (Optional)
    • Beschreibung: Gibt den herunterladbaren Bericht für den angegebenen Git-Commit-SHA zurück.
    • Beispielverwendung: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Beispiel curl Anfrage

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>'

Beispiel des Antwortkörpers

{
  "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
      }
    ]
  }
}

Antwortobjekt

Die folgenden Abschnitte beschreiben die JSON-Objekte im Antwortkörper.

Übergeordnete Struktur

source Objekt

Enthält Informationen über das Produkt, das den Bericht erstellt hat:

test_details Objekt

Enthält Informationen über die Testausführung:

commit Objekt

Enthält Informationen über den Git-Commit, der dem Test zugeordnet ist:

devhub_summary Objekt

Enthält zusammengefasste Informationen über gefundene Barrierefreiheitsprobleme:

issue_count_by_impact Objekt

Unterteilt die Probleme nach Auswirkungsgrad:

issue_count_by_rule Array

Jedes Objekt in diesem Array stellt eine Regel mit folgender Struktur dar:

Zusätzliche Antworten

202 Processing

Diese Antwort zeigt an, dass der Bericht noch generiert wird und Sie Ihre Anfrage nach einer Wartezeit erneut versuchen müssen.

Antworttext

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

400 Bad Request

Der angegebene Wert für commit_sha ist kein SHA-1-Wert.

Antworttext

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

401 Unauthorized

Eine der folgenden Fehlermeldungen wird die 401 Unauthorized Antwort begleiten.

Der angegebene API-Schlüssel ist nicht gültig

Antworttext

{
  "error": "Invalid API key"
}

Es gibt keinen erforderlichen Header mit einem API-Schlüssel:

Antworttext

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

404 Not Found

Eine der folgenden Fehlermeldungen wird die 404 Not Found Antwort begleiten.

Der verwendete SHA-Wert bei commit_sha konnte nicht gefunden werden

Dieser Fehler zeigt an, dass es für diesen SHA keine Daten im Axe Developer Hub gibt, was normalerweise bedeutet, dass die Testsuite nicht gegen diesen Git-Commit ausgeführt wurde. Beachten Sie, dass dies derselbe Fehler ist, der mit einem Zweignamen zurückgegeben wird, der nicht existiert. (Siehe den nächsten Fehler.)

Antworttext

{
  "error": "Session not found"
}

Der angegebene Wert für branch_name existiert nicht

Diese Fehlermeldung ist dieselbe wie der vorherige Fehler (wenn der mit dem commit_sha Abfrageparameter angegebene SHA nicht in den Daten des Axe Developer Hub existiert).

Antworttext

{
  "error": "Session not found"
}

Der angegebene Wert für project_id existiert nicht

Diese Fehlermeldung ist dieselbe wie die vorherigen 404 Fehler.

Antworttext

{
  "error": "Session not found"
}

Umgang mit einer 202 Processing Antwort

Dieses Beispiel-Shell-Skript zeigt, wie man curl verwendet, um Ihren Bericht erneut anzufordern, wenn Sie eine 202 Processing Antwort erhalten. Da Testsuiten zahlreiche Barrierefreiheitsverletzungen finden können, benötigt unser System möglicherweise zusätzliche Zeit, um alle Ergebnisse zu verarbeiten, bevor der Bericht zum Download bereitsteht. Wir empfehlen, das untenstehende Beispiel zu verwenden, um ein Skript zu erstellen, das kontinuierlich versucht und prüft, ob die Ergebnisse bereits verfügbar sind. Es wird die Anfrage bis zu 20 Mal wiederholen, mit einer Verzögerung von fünf Sekunden zwischen den Versuchen.

Das Beispiel erfordert, dass die API_KEY Umgebungsvariable auf Ihren API-Schlüssel gesetzt wird und PROJECT_ID auf Ihre Projekt-ID gesetzt wird.

#!/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