Ottieni Risultati Programmicamente

Il servizio REST dei report scaricabili ti consente di scaricare un riepilogo dei tuoi risultati di accessibilità dell'Axe Developer Hub come dati JSON, per ulteriori elaborazioni o importazione in altri software. Il servizio GET ha due parametri obbligatori:

• Chiave API - Trova una chiave API personale corrispondente al tuo progetto o aggiungi una nuova chiave API nel Portale Account Axe. Scegli una chiave API di Axe Developer Hub se il tuo progetto utilizza le API web, la CLI o il Watcher. Usa una chiave API di Axe DevTools Mobile per i progetti mobili.
• ID Progetto - Fornisci l'ID del progetto per i dati del progetto corrispondente che desideri scaricare. Trova il tuo ID progetto in Axe Developer Hub.

Puoi utilizzare due parametri opzionali per limitare la tua query a un ramo Git specifico o a uno specifico SHA del commit Git.

Riepilogo Richiesta

• Endpoint: https://axe.deque.com/api-pub/watcher/downloadable/report
• Richiesta: GET
• Intestazioni (Obbligatorie):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Parametri di query:
  • project_id (Obbligatorio)
    • Descrizione: Specifica l'ID del progetto per il report del progetto che vuoi scaricare. Questo parametro è obbligatorio.
    • Esempio d'uso: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>
  • branch_name (Opzionale)
    • Descrizione: Restituisce il report scaricabile per il nome del ramo Git specificato.
    • Esempio d'uso: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&branch_name=<GIT_BRANCH>
  • commit_sha (Opzionale)
    • Descrizione: Restituisce il report scaricabile per lo specifico SHA del commit Git.
    • Esempio d'uso: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Esempio curl Richiesta

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

Esempio del Corpo della Risposta

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

Oggetto della Risposta

Le sezioni seguenti descrivono i JSON object nel corpo della risposta.

Struttura di Livello Superiore

source Oggetto

Contiene informazioni sul prodotto che ha generato il report:

test_details Oggetto

Contiene informazioni sull'esecuzione del test:

commit Oggetto

Contiene informazioni sul commit Git associato al test:

devhub_summary Oggetto

Contiene informazioni riassuntive sui problemi di accessibilità trovati:

issue_count_by_impact Oggetto

Suddivide i problemi per livello di impatto:

issue_count_by_rule Array

Ogni oggetto in questo array rappresenta una regola con la seguente struttura:

Risposte aggiuntive

202 Processing

Questa risposta indica che il rapporto è ancora in fase di generazione e che è necessario riprovare dopo un'attesa.

Corpo della risposta

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

400 Bad Request

Il valore fornito per commit_sha non è un valore SHA-1.

Corpo della risposta

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

401 Unauthorized

Uno dei seguenti messaggi di errore accompagnerà la 401 Unauthorized risposta.

La chiave API specificata non è valida

Corpo della risposta

{
  "error": "Invalid API key"
}

Non c'è intestazione richiesta con una chiave API:

Corpo della risposta

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

404 Not Found

Uno dei seguenti messaggi di errore accompagnerà la 404 Not Found risposta.

Il valore SHA usato con commit_sha non può essere individuato

Questo errore indica che non ci sono dati per questo SHA nei dati dell'Axe Developer Hub, il che di solito significa che la suite di test non è stata eseguita contro questo commit Git. Nota che questo è lo stesso errore restituito con un nome di branch che non esiste. (Vedi il prossimo errore.)

Corpo della risposta

{
  "error": "Session not found"
}

Il valore fornito per branch_name non esiste

Questa risposta di errore è la stessa del precedente errore (se lo SHA fornito con il commit_sha parametro query non esiste nei dati dell'Axe Developer Hub).

Corpo della risposta

{
  "error": "Session not found"
}

Il valore fornito per project_id non esiste

Questa risposta di errore è la stessa degli errori precedenti 404 .

Corpo della risposta

{
  "error": "Session not found"
}

Gestire una 202 Processing risposta

Questo script shell dimostrativo mostra come utilizzare curl per richiedere nuovamente il rapporto se si riceve una 202 Processing risposta. Poiché le suite di test possono trovare numerose violazioni dell'accessibilità, il nostro sistema potrebbe richiedere ulteriore tempo per elaborare tutti i risultati prima che il rapporto sia pronto per il download. Si consiglia di utilizzare l'esempio qui sotto per creare uno script che riprovi continuamente e verifichi se i risultati sono già disponibili. Ripeterà la richiesta fino a 20 volte, con un intervallo di cinque secondi tra tentativi.

L'esempio richiede che la variabile di ambiente API_KEY sia impostata sulla tua chiave API e PROJECT_ID sia impostata sul tuo ID progetto.

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