Avvio rapido: la prima connessione ad Azure DevOps

Il percorso più breve da «il plugin è installato» a «una connessione segnala ok e nessun token sta nella configurazione». Quattro passi, circa quindici minuti.

Prerequisiti

wkdoado, wkdocore, wkdostorage e wkcore sono installati e attivati.
L'estensione PHP curl è presente. Senza di essa la schermata segnala che il connettore è inattivo.
Esiste un progetto DWDO — vedi l'avvio rapido di wkdocore. Senza il record del progetto la connessione non si può salvare.
In quel progetto avete il ruolo Manutentore. L'elenco delle connessioni può vederlo anche un lettore, ma non può crearne.
Un token di accesso personale (PAT) dell'organizzazione, con i minori ambiti possibili.
Un posto per quel token: wkvault o una directory fuori dalla radice web.

Passo 1: consentire l'host — prima non funziona nulla

Amministrazione → Configurazione, sezione wkdoado, impostazione ado_host_allow.

L'elenco è di fabbrica vuoto, e vuoto vieta tutto. Non è un filtro sopra un client altrimenti aperto: è l'intero permesso di inviare una richiesta.

Inserire il nome host esatto, uno per riga o separati da virgola:

dev.azure.com

Nessun carattere jolly, nessun modello. L'elenco nomina i luoghi con cui questo wiki può parlare, e un modello sarebbe una promessa su luoghi che nessuno ha enumerato.

Se il nome host risolve a un indirizzo di loopback o privato — nel caso di un'installazione propria è la norma — impostare anche ado_allow_private = 1. In questa installazione ado_host_allow vale devops.wvds.it e ado_allow_private vale 1.

Passo 2: mettere il token dove si possa riferirlo

Non inserite il token nella configurazione di questo plugin. Deliberatamente non esiste un campo per farlo.

O lo conservate in cassaforte e vi rimandate (vault:ado-pat-acme), oppure impostate ado_secret_root su una directory fuori dalla radice web e vi depositate il token come file. Anche quell'impostazione è vuota di fabbrica e disabilita quindi del tutto i riferimenti a file — chiuso nel dubbio, come l'elenco dei permessi.

Passo 3: creare la connessione

La connessione appartiene a esattamente un progetto DWDO e perciò non si configura nell'amministrazione, bensì su una pagina di progetto. Aprire una pagina di progetto e aggiungere l'azione:

/doku.php?id=it:projects:acme:start&do=wkdoado

Compilare sotto Aggiungi connessione:

Campo	Che cosa vi va
Chiave	L'identificatore della connessione; `[A-Za-z0-9_-]`, al massimo 64 caratteri.
Titolo	L'etichetta nell'elenco.
Distribuzione	`services` per il servizio `dev.azure.com`, `server` per un'installazione propria.
URL di base	L'indirizzo di base del server.
Organizzazione (services) / Collection (server)	A seconda della distribuzione.
Versione API	Predefinita `7.0`.

Scegliere Aggiungi e poi, nella riga della connessione, impostare tramite Imposta segreto il riferimento del passo 2.

Con la distribuzione server la collection fa di norma già parte dell'URL di base. Se compilate anche il campo Collection (server), viene aggiunta una seconda volta e ogni chiamata finisce con HTTP 404. Nominate la collection in un solo punto.

Passo 4: provare

Scegliere Prova nella riga della connessione.

Verifica del risultato

La colonna Stato è su ok. Quando la prova fallisce ne nomina la causa invece di emettere un unico verdetto — e le cause richiedono davvero risposte diverse:

Stato	Significato
host bloccato	Manca il passo 1 oppure il nome host non coincide esattamente.
irraggiungibile	DNS, instradamento, o un indirizzo privato senza `ado_allow_private`.
errore TLS	La verifica del certificato è fallita. La verifica è sempre attiva; per un'autorità di certificazione propria esiste `ado_ca_bundle`.
non autorizzato	Il token è errato, scaduto o privo dell'ambito necessario.

Controprova: nella configurazione di wkdoado non c'è alcun token — solo un riferimento nella connessione.

Passo successivo

wkdoadogit — rendere visibile nel wiki un repository di quell'organizzazione.
wkvault — creare la voce in cassaforte a cui il riferimento punta.
wkdoado (in tedesco) — la pagina del pacchetto: il client, lo strato di protezione e tutte e otto le impostazioni, tra cui il limite ado_max_bytes che tronca un risultato grande invece di trasmetterlo in flusso.