Ottenere risultati programmaticamente

Migrazione all'API Sessioni e Risultati

Il nuovo API Sessioni e Risultati sostituisce questo endpoint con due endpoint separati: uno per elencare le sessioni di un progetto e uno per recuperare i risultati di una sessione specifica. Questo modello a due fasi consente di accedere a tutte le sessioni attraverso i rami e i commit, non solo a quello più recente.

Richiesta equivalente usando format=summary

La modalità format=summary dell'endpoint Risultati restituisce lo stesso formato JSON di questo endpoint. Per replicare una richiesta esistente, prima trova la sessione che corrisponde al tuo ramo o commit, poi richiedi i suoi risultati:

1. Elenca sessioni per trovare la session_id per il ramo o il commit di tuo interesse, utilizzando i filtri git_branch o 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. Richiesta risultati per quella sessione tramite session_id, utilizzando format=summary per lo stesso formato JSON di questo endpoint:

   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

   Il nuovo endpoint restituisce 204 No Content mentre i risultati stanno venendo generati, non 202 Processing come fa questo endpoint. Se hai codice esistente che verifica una risposta 202, aggiorna per gestire invece 204. Vedi Stato della sessione e Schema di Polling per un esempio completo di polling.

Approfondimenti con format=full

Se desideri dettagli completi a livello di problema oltre a quanto fornito dal sommario, usa format=full per recuperare i risultati in JSON Universale (Formato Comune di Esportazione). Questo formato include ogni problema di accessibilità trovato durante la sessione: violazioni individuali, controlli incompleti, passaggi e regole inapplicabili organizzati per pagina.

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"

Riferimento a Endpoint di Eredità

Il servizio REST report scaricabili ti consente di scaricare un riepilogo dei tuoi risultati di accessibilità di 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 Axe Developer Hub se il tuo progetto utilizza le API web, CLI o Watcher. Usa una chiave API Axe DevTools Mobile per progetti mobile.
• ID Progetto - Fornisci l'ID del progetto per i dati del progetto corrispondente che vuoi scaricare. Trova il tuo ID progetto in Axe Developer Hub.

Puoi utilizzare due parametri opzionali per limitare la tua query a uno specifico ramo Git 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 di utilizzo: 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 di utilizzo: 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 SHA del commit Git specificato.
    • Esempio di utilizzo: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Esempio di Richiesta 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>'

Esempio di 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 gli oggetti JSON nel corpo della risposta.

Struttura di Alto Livello

Oggetto source

Contiene informazioni sul prodotto che ha generato il rapporto:

Oggetto test_details

Contiene informazioni sull'esecuzione del test:

Oggetto commit

Contiene informazioni sul commit Git associato al test:

Oggetto devhub_summary

Contiene informazioni di riepilogo sui problemi di accessibilità trovati:

Oggetto issue_count_by_impact

Suddivide i problemi per livello di impatto:

Array issue_count_by_rule

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

Risposte aggiuntive

202 Processing

Questa risposta indica che il report è ancora in fase di generazione e che è necessario riprovare la richiesta dopo aver atteso.

Corpo della risposta

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

429 Too Many Requests

Durante periodi di carico elevato, questo endpoint può rispondere con 429 Too Many Requests invece di avviare immediatamente l'elaborazione. Il lavoro sottostante rimane in coda, quindi riprovare non crea elaborazioni duplicate. La risposta include un'intestazione Retry-After, in secondi — attendere almeno quel tempo prima di riprovare.

Corpo della risposta

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

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 risposta 401 Unauthorized.

La chiave API specificata non è valida

Corpo della risposta

{
  "error": "Invalid API key"
}

Non esiste un'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 risposta 404 Not Found.

Il valore SHA usato con commit_shanon è stato trovato

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

Corpo della risposta

{
  "error": "Session not found"
}

Il valore fornito per branch_namenon esiste

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

Corpo della risposta

{
  "error": "Session not found"
}

Il valore fornito per project_idnon esiste

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

Corpo della risposta

{
  "error": "Session not found"
}

Gestire una risposta 202 Processing

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

Il campione richiede che la variabile d'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