REST API¶
La nuova API HTTP/JSON espone le operazioni aziendali dal catalogo MCP senza una busta JSON-RPC. Le operazioni disponibili dipendono dalla versione installata del server. Si tratta di un'API orientata al funzionamento, non di un'interfaccia CRUD separata per ogni tabella di database.
Accesso e autorizzazioni¶
Inviare una chiave API MCP esistente come Authorization: Bearer <key>. MCP deve essere abilitato a livello globale e per il progetto. Le chiavi del progetto richiedono anche X-ZTM-Project-UniqueId. Le chiavi globali hanno bisogno di un accesso esplicito al progetto per le operazioni di progetto. Browser e Windows sign-in non sostituiscono una chiave API.
Le autorizzazioni dell'utente, le cancelli di scrittura, le capacità consentite e le restrizioni demo si applicano proprio come fanno per MCP. Utilizzare HTTPS al di fuori dei test locali. Non mettere mai le chiavi in URL, codice sorgente o registri. Vedi Azioni sicure e MCP.
Scopri le operazioni¶
| Richiesta | Risultato |
|---|---|
GET /api/v1/operations |
Operazioni e contratti di input disponibili alla chiave e al progetto corrente |
GET /api/v1/operations/{operationId} |
Un contratto di funzionamento |
GET /api/v1/openapi.json |
OpenAPI 3.1 per lo stesso contesto di autorizzazione |
POST /api/v1/operations/{operationId} |
Eseguire con l'oggetto argomento come corpo richiesta |
POST /api/v1/resources/read |
Leggi una risorsa di esportazione a portata di chiave |
OpenAPI contiene un percorso POST concreto per ogni operazione disponibile. Gli input utilizzano gli stessi schemi del MCP. La salute della biblioteca, la stabilità dei risultati, gli allegati del progetto e i confronti di rilascio/snapshots hanno digitato gli schemi di uscita. Altri risultati di query/action dinamici conservano contratti JSON estensibili. Il catalogo include query e strumenti di azione condivisi; non ogni voce del menu Web ha un endpoint dedicato.
$headers = @{
Authorization = "Bearer $env:ZTM_API_KEY"
'X-ZTM-Project-UniqueId' = $env:ZTM_PROJECT_UNIQUE_ID
}
$baseUrl = 'https://your-server.example'
Invoke-RestMethod "$baseUrl/api/v1/operations" -Headers $headers
Invoke-RestMethod "$baseUrl/api/v1/operations/ztm_usage_guide" `
-Method Post -Headers $headers -ContentType 'application/json' -Body '{}'
Queste variabili di ambiente vengono lette dallo script di chiamata PowerShell; non configurano automaticamente il server. Progetti di percorso che utilizzano intestazioni, non argomenti di funzionamento. I corpi JSON sono limitati a 1 MiB e 32 livelli di nidificazione. I nomi di proprietà duplicati sono respinti.
Leggi l'impostazione di anteprima dell'Ufficio¶
Una chiave API MCP globale può leggere l'efficace modalità XLSX dell'installazione con POST /api/v1/operations/ztm_admin_office_preview_settings_get e il corpo {}. Una risposta di esempio è {"xlsxPreviewMode":"HtmlTable"}; l'altro valore possibile è DevExpressPdf. Una chiave di progetto è insufficiente. Questa operazione è solo in lettura. Utilizzare amministrazione del server per modificare l'impostazione.
Scritti ed esportazioni¶
Seguire l'anteprima di ogni operazione e il contratto di commit esplicito, ad esempio ztm_project_action_prepare e ztm_project_action_commit. L'accesso API non sostituisce l'approvazione aziendale. Mantenere anteprime, chiavi di idempotency e si impegna legato allo stesso contesto utente e progetto. Dopo un timeout, controllare lo stato dell'azione piuttosto che ripetere ciecamente una scrittura.
Le esportazioni possono restituire un resourceUri. Leggilo attraverso POST /api/v1/resources/read con {"uri":"<resourceUri>"} utilizzando la stessa chiave e il progetto. La risposta contiene contents con dati di testo o Base64 e un tipo MIME. I biglietti possono scadere o consentire una sola lettura; trattare gli URI delle risorse come riservati.
Errori¶
Errori restituiscono lo stato HTTP e application/problem+json contenente code e traceId: 400 ingresso non valido, 401 autenticazione mancante/rigettata, 403 autorizzazioni insufficienti, 404 oggetto o funzionamento non disponibile, 409 conflitto d'azione, 413 corpo oversize, 415 tipo di contenuto non supportato, 500 guasto interno. I conflitti richiedono la revisione, non i retries automatici. Dare supporto al traceId, mai chiavi o carichi di pagamento riservati.
Prerequisiti regole e test bloccati¶
ztm_project_query include rule per la libreria e le dipendenze pianificate: 0 = Solo colpo, 1 = Deve avere successo, 2 = Non deve aver fallito.
Per modificare una dipendenza della libreria esistente, utilizzare ztm_project_action_context, quindi ztm_project_action_prepare con capabilityId: project.test-case.dependency.set-rule e argomenti testCaseId, dependencyId, rule. Verificare l'anteprima e confermarlo con ztm_project_action_commit. La chiave richiede questa esplicita capacità di scrittura. La creazione rimane compatibile: una nuova relazione inizia come un suggerimento; la sua regola può quindi essere cambiata. I piani esistenti e le corse non sono sincronizzati automaticamente.
POST /api/v1/operations/ztm_test_prerequisites_read con {"plannedVariantId":123} valuta un test pianificato visibile. La risposta include isBlocked, needsRecheck e blockers. I predecessori invisibili o mancanti non sono divulgati per nome; hasHiddenPrerequisites li indica. Questa valutazione puntuale non concede diritti di esecuzione o sostituisce la conferma personale del riesame. La stessa operazione è disponibile tramite MCP.
Attacchi di progetto¶
ztm_project_attachments_read elenca gli allegati di progetto e il loro ownerId, con offset e limit (maxum 100). Fornire attachmentId per scaricare contentBase64 (massimo 32 MiB). È richiesto un amministratore di progetto attivo o un project manager. I file collegati dinamicamente sono elencati ma non possono essere scaricati attraverso questa operazione.
Le scritture richiedono la capacità project.attachment.upload, project.attachment.update o project.attachment.delete separata. Le attuali sovvenzioni per l'adesione alla pianificazione non consentono l'accesso ai file di progetto. Utilizzare il ownerId restituito, che può essere 0 per un progetto.
- Caricamento: chiama
ztm_project_attachment_stagecontargetKind: "project",targetId: <ownerId>,fileName,mimeTypeecontentBase64. Il limite di staging esistente è 512 KiB per file. - Chiama
ztm_project_action_preparecon la capacità, un nuovoidempotencyKeyearguments. Argomenti di caricamento:ownerKind: "project",ownerId,attachmentReferenceIddel biglietto,displayNameopzionale eremarks. Aggiornamento dei metadati:ownerKind,ownerId,attachmentId,displayName,remarks. Elimina:ownerKind,ownerId,attachmentId. - Verificare l'anteprima e confermare tramite
ztm_project_action_commitcon la stessa chiave. Le modifiche concomitanti causano un conflitto; la riproduzione di un commit di successo non crea un altro attaccamento.
Confronti e decisioni di rilascio¶
ztm_release_snapshots_list elenca i confronti salvati leggibili con un filtro targetId opzionale. Passare il NextCursor restituito come cursor per leggere la pagina successiva.
ztm_release_compare accetta baseId, targetId, baseRunIds/targetRunIds esplicita e opzionali array baseScopeRunIds/targetScopeRunIds di { "runId": 123, "scopeRunId": 123 }. Opzionale baseSnapshotId/targetSnapshotId seleziona le prove salvate. restituisce il confronto Web tra cui Fingerprint, applicando la stessa selezione e le regole di permissione degli oggetti.
Per salvare le prove, concedere esplicitamente project.release-review.snapshot-create e preparare/commettere argomenti query (l'oggetto argomento di confronto), name e fingerprint. I cambiamenti delle prove sono respinti. Leggi il confronto salvato, decisionRevision e la cronologia delle decisioni con ztm_release_snapshot_read e snapshotId; le decisioni precedenti di pagine historyBeforeRevision.
Una decisione richiede anche project.release-review.decision-record, il permesso di gestione del progetto e l'autorizzazione umana esplicita. Prepara accetta snapshotId, targetId, revision, outcome (1 accettato, 2 accettato con condizioni, 3 rifiutato, 4 revocato), responsibleUserId, comment, openPoints (uno per linea) e humanConfirmed: true. Il server registra l'attore autenticato; la bandiera non sostituisce l'effettiva approvazione umana. Rivedere l'anteprima, quindi commettere. Si applicano ancora le regole del Web: la revisione corrente, l'utente responsabile idoneo, la spiegazione, la portata completa e le prove invariate. Le copie del progetto storico non possono ricevere una nuova decisione.
Copertura e limiti¶
REST e MCP condividono il loro catalogo operativo. Questo non implica una copertura completa di ogni funzione Web. Gli allegati del progetto ora hanno un contratto di scrittura separato; i contratti di prova esistenti, il requisito e la pianificazione di upload rimangono separati. Le operazioni differite rimangono visibili nel catalogo delle capacità.
La presentazione del browser, le finestre di dialogo di file-picker e il login interattivo non hanno bisogno di endpoint di dominio separati. La conferma personale di un vero e proprio ripetitore manuale non viene generata automaticamente per conto di un tester. Panoramica di rilascio/PDF e le importazioni di automazione utilizzano le loro operazioni esistenti; il trasporto REST non espande la loro copertura di dominio. Gli allegati del progetto scrivono e rilasciano le operazioni di confronto/decisione sono ora disponibili come descritto sopra. I percorsi dei server arbitrari e i link dei file di Local Bridge rimangono al di fuori di queste operazioni API. La copia e le importazioni di file manifesti non sono azioni separate nell'implementazione web controllata. Le uscite di tipo coprono gli allegati del progetto e i confronti di rilascio/snapshots; le uscite di query/action dinamiche esistenti rimangono estensibili JSON, non completamente modellati modelli SDK.
Versioni dei casi di prova¶
Versione del caso di prova è disponibile tramite POST /api/v1/operations/ztm_project_test_case_versions. Utilizzare operation: "list", testCaseID e skip opzionale e take per un elenco limitato con la testa corrente. read richiede anche revisionID, mentre compare aggiunge otherRevisionID; asset utilizza revisionID e assetID e restituisce byte codificate base64. restore-preview controlla revisionID contro expectedHead.
Preparare il restauro attraverso ztm_project_action_prepare, la capacità project.test-case-version.restore e gli argomenti testCaseID, revisionID, expectedHead, note opzionale e options. Confermare il token restituito tramite ztm_project_action_commit. options può contenere esplicitamente escluso excludedAttributeIDs e flattenUnavailableReusableSteps. Si applicano ancora gli ambiti di scrittura e la protezione demo, l'identità attiva dell'utente, le autorizzazioni degli oggetti, i campi di applicazione e la protezione demo. Non mettere mai le chiavi API in esempi, registri o cronologia shell.
Salute della biblioteca e stabilità dei risultati¶
Queste operazioni di lettura utilizzano gli stessi servizi e le autorizzazioni degli oggetti dei report Web. Non è richiesto alcun sussidio di scrittura. Non modificano, eliminano o eseguono i test.
| Operazione | Filtri opzionali |
|---|---|
ztm_library_health_read |
unitId compresi i discendenti o caseId; ageDays 1–36500 (default 180); reason; page da 1; pageSize 1–100 (default 50) |
ztm_test_stability_read |
testPlanId; testEnvironmentId (0 per nessun ambiente); fromUtc, toUtc come timestamp UTC come 2026-11-08T12:00:00Z; lookbackRuns 1–200 (default 50) |
Esempio: POST /api/v1/operations/ztm_library_health_read con {"ageDays":180,"reason":"NoVisibleUsage","pageSize":25}. La risposta digitata include Findings, CandidateCount, ScannedCaseCount, IsComplete, Limit, Page e PageSize. Le ragioni sono NoVisibleUsage, NeverVisiblyExecuted, LongUnchanged, MissingTitle, MissingSteps, MissingExpectedResults, EmptyQuickContent e NoVariants. Le ragioni possono sovrapporsi. Nessun utilizzo visibile non stabilisce che un test non venga utilizzato in tutto il progetto; il contenuto a lungo non modificato non è automaticamente obsoleto. L'analisi è limitata a 2000 casi visibili e 20000 usi visibili. Quando l'analisi dell'uso è incompleta, gli indicatori di utilizzo negativi vengono soppressi.
Esempio: POST /api/v1/operations/ztm_test_stability_read con {"lookbackRuns":50}. La risposta include Series, FailureGroups, Evidence individuale e i conteggi EligibleRuns, IncludedRuns, EligibleResults, IncludedResults, Truncated e InvalidEvidenceCount. Utilizza il risultato corrente per run/case/variant in corse rifinite visibili, non la storia completa dell'esecuzione. Al massimo 20000 osservazioni di risultato sono analizzate. Varianti, ambienti e origine sono separati; le differenze di costruzione rimangono visibili. ContentDifferences e ContentFingerprint confrontano solo la descrizione della cassa di prova salvata, non le specifiche storiche complete. I cambiamenti dei risultati sono indicatori, non prova di flakiness. Il testo di errore di corrispondenza non dimostra una causa condivisa. Origin: 0 = automazione corrente verificata, 1 = origine diversa o non verificata, 2 = prova di automazione modificata o non valida.
Utilizzare l'involucro di ingresso mostrato. Gamme non valide, timestamp o filtri sconosciuti restituiscono 400; oggetti espliciti di librerie non leggibili restituiscono 403. Gli stessi strumenti e filtri sono disponibili tramite MCP.
Linee di riferimento¶
Linee di riferimento fornisce operazioni digitate per opzioni di campo, elenco, contenuti storici, confronto corrente e file salvati. La creazione utilizza la preparazione/commissione con la funzionalità project.library-baseline.create esplicitamente concessa; non c'è alcuna operazione di modifica, ripristino o cancellazione. Vedere il capitolo collegato per i nomi degli strumenti, argomenti di portata, regole di riprovazione e il limite 512 KiB per le risposte dei file API.
Pianificazione degli alberi e dei risultati personalizzati¶
ztm_project_planning_tree_read restituisce l'albero di pianificazione consentito insieme alle definizioni dei risultati disponibili e ai filtri di esecuzione. Esempio di richiesta:
{"resultDefinitionIds": [12, 15], "includeNoResult": true}
Utilizzare ID effettivi da resultDefinitions; gli ID di esempio sono segnaposto. Gli ID di stato usano OR; l'opzionale treeFilterObjectId limita ulteriormente le piste. Selezioni omesse non significano filtri per tale richiesta, indipendentemente dalle preferenze dell'interfaccia utente salvate. Il risultato segue le impostazioni di visibilità dell'albero dell'utente e restituisce solo nodi consentiti. I documenti espliciti sconosciuti sono respinti. L'operazione di lettura non modifica preferenze personali o risultati dei test. Lo stesso contratto è disponibile tramite MCP.
Attribuire l'origine del valore¶
Per le azioni di attributo esistenti, ztm_project_action_context aggiunge Metadata a PromotedFields e ObjectAttributes. Include AttributeId, AttributeStyleFieldId, nome di campo, ID stile e nome, tipo di campo, tipo proprietario e ID, Entail e SourceKind (direct, inherited, default). Un default non salvato non ha nessun ID proprietario. Le definizioni dei campi mancanti conservano il loro ID sul campo originale mentre i loro dettagli di definizione sono nulli.
Le stesse informazioni sono disponibili tramite MCP e POST /api/v1/operations/ztm_project_action_context. Le autorizzazioni e le capacità dell'azione dell'attributo esistenti sono ancora applicabili; l'accesso al contesto non concede il permesso di lettura aggiuntivo. I campi di password sono esclusi. Il contesto di lettura non persiste nei difetti. Attributi spiega la differenza tra eredità per nome e campi promossi.
Risposte mirate dei risultati¶
Gli strumenti di sola lettura ztm_result_feedback_read, ztm_result_feedback_preview e ztm_result_feedback_export sono disponibili anche come operazioni POST sotto /api/v1/operations/. Ciascuno richiede la sua capacità di lettura project.result-feedback.read, .preview o .export, oltre a leggere l'accesso agli oggetti selezionati.
read accetta testRunId. preview aggiunge resultItemIds (1 a 100 ID unici), in modo facoltativo recipient, subject, message, externalReference e includeResultText (default false). La sua risposta include Fingerprint dei contenuti recensiti. export utilizza lo stesso input più expectedFingerprint, format (html o xlsx) e opzionalmente language (de o en). La risposta contiene FileName, ContentType e ContentBase64.
Il contenuto modificato richiede un'altra anteprima. I risultati selezionati inaccessibili rifiutano l'intero output; non vi è alcuna esportazione parziale silenziosa. Nessuna operazione invia messaggi o memorizza i destinatari del progetto. Vedere Risultati dei test per i limiti di flusso e contenuto dell'utente.
Regole di ruolo AD¶
ztm_ldap_role_rules_get legge le regole di una configurazione di importazione; ztm_ldap_role_rules_save li salva con una revisione prevista; ztm_ldap_role_rules_preview prevede modifiche di appartenenza. ztm_ldap_import_run gestisce l'importazione di AD esistente, comprese le regole salvate. Le stesse operazioni sono disponibili come strumenti MCP.
Tutte le chiamate richiedono configurationId. Salva, anteprima e importazione richiedono anche expectedRevision dalla risposta di lettura più recente. Salva accetta rules contenente ID di regola stabili, stato abilitato, nome attributo, valore esatto, ruolo e un nome di gruppo dedicato. I chiamanti non scelgono gli ID di gruppo. I contratti Generated OpenAPI descrivono i campi completi.
Salvare e importare sono le scritture amministrative che richiedono una chiave amministrativa abilitata con l'accesso al progetto e la portata corrispondente. Anche le autorizzazioni di gestione del progetto sono controllate. L'anteprima non cambia i membri, ma ha bisogno di accedere alla directory configurata. La demo pubblica blocca queste chiamate di amministrazione. Sul conflitto di revisione, leggere e rivedere la configurazione di nuovo piuttosto che riprovare ciecamente un'importazione con impostazioni obsolete.
Valutazione dei difetti di rilascio e di freschezza¶
ztm_release_evidence_read, ztm_release_evidence_configure e ztm_release_evidence_observe leggono limiti di età o memorizzano i limiti e valutano esplicitamente i difetti manuali. Usano i contratti MCP corrispondenti e l'attuale expectedRevision. Rileggere dopo il conflitto (409); non riprovare ciecamente. observe richiede l'effettivo referenceId e sourceFingerprint dalla panoramica report.EvidenceAssessment.Defects, più state, criticality, observedUtc con un fuso orario esplicito e comment.
Gli ambiti di scrittura dedicati sono project.release-evidence.configure e project.release-evidence.observe. Abilitato il progetto scrive e le stesse autorizzazioni di gestione del rilascio come Web anche applicare. Le dichiarazioni includono l'utente di registrazione e il tempo; non vengono verificati automaticamente i dati del tracker e non devono essere inventati senza istruzioni umane esplicite. ztm_release_overview_read aggiunge EvidenceAssessment per nuove catture live; il livello assessment esistente e le ragioni lo incorporano. Le catture storiche rimangono invariate. Vedi Confronto e accettazione della release.
Set di dati di prova strutturati¶
Questi strumenti MCP sono disponibili anche come POST /api/v1/operations/<tool-name> con gli stessi contratti. Vedere Matrice di dati di prova per regole funzionali.
Strumento (prefisso ztm_test_data_set_) |
Argomenti | Risultato |
|---|---|---|
list |
Nessuno | set di dati consentiti in items |
read |
dataSetId |
set di dati con revisione e ID file stabili |
save |
data, expectedRevision, confirmed:true |
dati perseverati con una nuova revisione |
delete |
dataSetId, expectedRevision, confirmed:true |
deleted:true; i dati di riferimento rimangono protetti |
binding |
variantId |
binding o null |
preview |
variantId, dataSetId, rowId |
testi, diagnostica e impronta digitale senza modifiche |
apply |
argomenti di anteprima, expectedFingerprint, confirmed:true |
testi vincolanti e risolti perseveranti |
unbind |
variantId, expectedFingerprint, confirmed:true |
unbound:true; i testi risolti sono conservati |
export |
dataSetId |
XLSX fileName, mimeType, contentBase64 |
import_preview |
dataSetId, expectedRevision, contentBase64 |
proposta non salvata; chiama esplicitamente save dopo |
I campi dei set di dati sono Id, TestUnitId, Name, Revision, Columns e Rows; le righe contengono Id e Values. La creazione utilizza il GUID zero per Id e un expectedRevision vuoto. Le righe richiedono GUID non zero unici. Gli aggiornamenti richiedono la revisione letto in precedenza. Dopo i conflitti, rileggete e riesaminate i cambiamenti.
Le quattro scritture richiedono ambiti individuali project.test-data-set.save, .delete, .apply o .unbind, le scritture di progetto abilitate e le autorizzazioni relative all'oggetto. Importa l'anteprima non persiste mai, ma richiede il permesso di modifica proprietario proprio come Web. Le restrizioni demo si applicano anche attraverso le API. REST utilizza le chiavi del portatore piuttosto che i cookie del browser e non richiede un token CSRF; i moduli Web richiedono ancora gettoni antiforgery.
XLSX utilizza un foglio di lavoro con _RowId come prima colonna. Le formule, le macro e i riferimenti esterni sono respinti. Limiti: 4 MiB XLSX, 16 MiB ha ampliato il contenuto, 30 colonne di dati, 1.000 righe, 32.767 caratteri per cella e 2 MiB per set di dati. Solo l'anteprima di salvataggio e di importazione accetta fino a 6 MiB JSON trasporto compreso Base64; altre operazioni mantengono il limite di 1-MiB esistente.
binding restituisce anche leganti congelati la cui fonte non è disponibile: SourceAvailable:false e diagnostica SourceUnavailable. Il testo salvato rimane leggibile quando la variante è leggibile. La raffinazione richiede l'accesso alla fonte; l'unbinding utilizza l'impronta digitale di legame corrente.
Importazione da un altro strumento di prova¶
La costruzione di sviluppo attuale fornisce POST /api/v1/operations/ztm_vendor_migration_preview e POST /api/v1/operations/ztm_vendor_migration_apply per migrazione da un altro strumento. Gli strumenti MCP equivalenti condividono questo contratto.
Fornire targetUnitId, sourceKey, workbookBase64 e facoltativamente attachmentsZipBase64.
Per una tabella del fornitore, aggiungere provider (testrail, xray, zephyr, qase o neutrale) e fileName che termina in .xlsx o .csv. Continua a inviare i byte in workbookBase64. Le colonne rilevate vengono utilizzate per impostazione predefinita. Utilizzare mapping per assegnare OutsideId, Nome, FolderPath, Descrizione, Prerequisiti, Passi, Risultato previsto e AttachmentPath alle voci esistenti. Utilizzare la stessa fonte, file e mappatura quando si applica l'anteprima. Le richieste Neutral XLSX senza questi campi mantengono il loro comportamento esistente.
Anteprima utilizza la capacità di lettura project.vendor-migration.preview. È sufficiente una chiave di lettura del progetto; il suo utente ha anche bisogno del permesso per creare casi nell'obiettivo. Non è necessario alcun campo di scrittura per l'anteprima. restituisce Fingerprint, Items, Diagnostics e CanApply senza salvare. Applicare solo quando CanApply è vero; rivedere una nuova anteprima dopo le modifiche.
Per applicare, inviare gli stessi file, l'anteprima di impronta digitale di expectedFingerprint, un UUID fresco come operationId e confirmed: true. Ripristinare la stessa operazione con lo stesso UUID dopo un'interruzione di rete.
L'applicazione richiede azioni di scrittura abilitate e l'ambito project.vendor-migration.apply. Le autorizzazioni di oggetti e le restrizioni demo corrispondono al flusso di lavoro Web. La richiesta di JSON, compresi i dati di Base64, è limitata a 6 MiB.
Quando il database del progetto è occupato, REST restituisce HTTP 503 con DatabaseBusy e Retry-After: 2. MCP restituisce actionErrorCode: "DatabaseBusy" e retryAfterSeconds: 2 nei dati di errore. Dopo l'uscita dell'accesso, riprovare la stessa richiesta con lo stesso operationId; le ricevute salvate vengono restituite dopo aver controllato i permessi e i contenuti attuali di nuovo, senza creare ulteriori copie.
Passare la mano su una prova¶
Utilizzare una chiave di progetto personale con il campo di scrittura project.test-run.handover per leggere i destinatari idonei e la revisione corrente. MCP e REST usano gli stessi argomenti.
- Chiama
ztm_project_action_contextcon{"capabilityId":"project.test-run.handover","itemKind":"test-run","itemId":23}. - Scegliere un ID da
Recipientse utilizzareRevisioncomeexpectedRevision. Ad esempio, chiamaztm_run_handoveroPOST /api/v1/operations/ztm_run_handovercon{"runId":23,"recipientUserId":7,"expectedRevision":0}.
Applied conferma che la consegna è stata salvata. mailStatus riporta lo stato di consegna (Sent, NotConfigured, MissingAddress, MissingLink o Failed). Ripetindo la richiesta per il destinatario corrente restituisce AlreadyApplied con mailStatus: null. Leggi nuovamente il contesto dopo un conflitto (HTTP 409). Il proprietario chiave ha bisogno del permesso di modificare l'esecuzione. Le chiavi globali e le istanze demo non possono eseguire consegne.
Assegnare i casi di prova previsti¶
- Utilizzare
ztm_project_action_contextper leggere lo stato corrente per ogni corsa. Invia{"capabilityId":"project.test-run.assign","itemKind":"test-run","itemId":23}. Scegliere i casi daCasese un destinatario daRecipients. - Chiama
ztm_run_assignin MCP o inviaPOST /api/v1/operations/ztm_run_assign. Per un caso non firmato, inviare per esempio{"recipientUserId":7,"selection":[{"caseId":42,"runId":23,"expected":null}]}. Se il caso è già assegnato, passare il suouserId,assignedUtceassignedByUserIdsottoexpected. PassarerecipientUserId: nullper cancellare l'assegnazione. - Leggere il carico di lavoro attraverso
ztm_run_workload_readoPOST /api/v1/operations/ztm_run_workload_readcon{"planId":9}.
La scrittura richiede una chiave personale con l'ambito project.test-run.assign, eseguire il permesso di modifica e l'accesso ai casi selezionati. Non è disponibile nella demo pubblica. In conflitto, leggere di nuovo lo stato attuale. Ogni richiesta salva la sua selezione in un'unica operazione. Il carico di lavoro include solo le piste aperte visibili.
Leggi la copertura di rilascio¶
- Chiama
ztm_coverage_matrix_readin MCP o inviaPOST /api/v1/operations/ztm_coverage_matrix_readcon{}.Releasescontiene gli ID e i nomi di rilascio visibili. - Inviare la
releaseIdselezionata e facoltativamentefilter. Ad esempio,{"releaseId":"6bebaee0-20b9-4ff8-b4d1-abdd5d37833c","filter":"without-result"}. I filtriall,without-test,without-resultefailedcorrispondono alla visualizzazione del browser. - Leggi
Rowsper esigenza, caso di prova e ambiente.Statusè 0 per nessun risultato, 1 per non valutabile, 2 per passato, 3 per fallito e 4 per parzialmente superato. Se le prove salvate sono visibili, le celle includonoResultItemId,RunTitle,RecordedUtceTester.Totalsconta requisiti filtrati. Un requisito può contribuire a diverse categorie.
Hai bisogno di una chiave di progetto personale e leggere l'accesso ai dati richiesti. La funzione Requisiti deve essere abilitata per il progetto. Questa operazione legge la matrice.
Creare e revocare un link di stato¶
Chiama ztm_share_link_create in MCP o POST /api/v1/operations/ztm_share_link_create in REST. Entrambi accettano lo stesso corpo JSON.
{"targetKind":"run","targetId":"23","validityDays":7,"requestId":"869744c5-8cdb-45e1-a300-918d308345f1","includeErrors":false,"includeFindings":false}
Impostare targetKind a run, plan o release. Fornire l'ID di destinazione come una stringa, utilizzando il suo UUID per un rilascio. Scegli 7 o 30 giorni. I problemi e i risultati sono nascosti per impostazione predefinita. Aggiungi recipientEmail per inviare il link tramite e-mail di progetto.
Tenere shareId per la revoca. La risposta restituisce l'indirizzo ospite in url una volta, insieme a expiresUtc e mailStatus (NotRequested, Sent o Failed). Risolvere un indirizzo relativo per gli ospiti contro l'origine dell'API endpoint. Trattare l'indirizzo, compreso il suo frammento, come una password. Se la consegna fallisce, il link è già stato creato. Ripristinare con lo stesso requestId non può creare un altro link o inviare un'altra email. Se la risposta è stata persa, revocare l'ingresso originale in Link condivisi prima di creare un sostituto.
Rivolgiti con ztm_share_link_revoke o POST /api/v1/operations/ztm_share_link_revoke e {"shareId":"<share UUID>"}. La risposta contiene shareId e revokedUtc. La revoca ripetuta restituisce il timestamp originale.
Entrambe le azioni richiedono HTTPS (loopback è consentito localmente), scrittura di progetto abilitata e una chiave di progetto personale con il relativo campo project.share-link.create o project.share-link.revoke. Le autorizzazioni di destinazione e le restrizioni demo si applicano come nel client web. Vedere accesso agli ospiti.
Modificare diversi casi di test¶
Chiama ztm_library_bulk_update in MCP o POST /api/v1/operations/ztm_library_bulk_update. Ad esempio, l'anteprima imposta un attributo del modulo:
{"operation":"preview","action":"attribute","caseIds":[12,31],"attributeName":"Modul","attributeValue":"Checkout"}
Controlla Rows. Quindi impostare operation a apply e inviare gli stessi parametri con Fingerprint restituito in fingerprint. Aggiungi un UUID in requestId per i retries. Ripetendo la stessa richiesta con l'ID restituisce la ricevuta mentre il server mantiene il lavoro. HTTP 409 richiede un'anteprima fresca.
Utilizzare targetUnitId con move o archive, reviewGroupId con review e variantValueIds con variant. Una destinazione d'archivio deve essere contrassegnata come un'unità di archivio. Ogni richiesta accetta fino a 200 casi di prova. Utilizzare una chiave di progetto personale con l'ambito project.test-library.bulk-update. Il server controlla i diritti correnti per ogni caso. Le chiavi globali e l'accesso demo sono bloccati.
Utilizzare {"operation":"undo","requestId":"<RequestId from receipt>"} con la stessa chiave di progetto per annullare le mosse o l'attributo modifiche mentre il lavoro rimane nella memoria del server. Le autorizzazioni e i cambiamenti intervenuti sono nuovamente controllati.
L'opzionale boolean isArchive negli argomenti project.test-unit.update segna un'unità come archivio. Utilizzare l'anteprima / il flusso di impegno esistente con itemId e title. Omettendo isArchive conserva il suo valore. L'unità di conoscenza del progetto legge anche esporre isArchive.
Riprova dei risultati selezionati¶
ztm_library_retest o POST /api/v1/operations/ztm_library_retest utilizza lo stesso flusso di lavoro di Mantenere la libreria di test:
- Invia a
operation: "options"efindingsdi leggere le sorgenti, gli ambienti e i tester consentiti. Ogni ricerca contienecaseId,plannedCaseIdoresultId; includevariantId,planIderunId. Scelga esplicitamente un contesto quando molti sono disponibili. - Invia
operation: "preview", la stessa selezione eplanId,runId,environmentetesterId.Itemselenca le varianti efficaci, compresi i prerequisiti obbligatori.Skippedidentifica i risultati esclusi dal loro indice di selezione zero-based. ImpostareacceptOldTemplate: truesolo dopo aver esplicitamente deciso di utilizzare modelli obsoleti. - Invia
operation: "create"con input identici, ilFingerprintrestituito comefingerprinteRequestIdcomerequestId. La ricevuta includeRunId,Urle i risultati saltati. Dopo un guasto di connessione, riprovare lo stesso ID di richiesta per evitare di creare un secondo run.
Le anteprime scadono dopo 30 minuti e appartengono al progetto e all'utente. Le modifiche alla selezione, autorizzazioni o contenuti richiedono un'anteprima fresca. Ogni richiesta accetta al massimo 200 risultati; è richiesto un'uscita di sorgente esistente. Il parametro tab opzionale (health, impact, results) controlla anche che la scheda corrispondente è disponibile.
Utilizzare una chiave di progetto personale con campo di scrittura project.test-library.retest e il permesso di creare run nel piano selezionato. Le chiavi di amministratore globali e la modalità demo pubblica sono escluse. Gli strumenti esistenti e la sincronizzazione attraverso project.planned-test-case.synchronize-from-library rimangono invariati.
Osservazioni degli oggetti¶
Utilizzare ztm_comment_read per leggere commenti e attività per un oggetto. Fornire kind (test-case, requirement, run, result) e id. offset e activityOffset pagina in modo indipendente. Utilizzare commentId per individuare la pagina contenente un commento. Tratta Markdown come contenuto utente.
ztm_comment_add salva markdown con un UUID generato dal cliente come commentId. Fornire parentId per rispondere. È possibile utilizzare mentionUserIds per notificare agli utenti di progetti esplicitamente selezionati l'accesso a lettura. Il testo deve includere la loro menzione. Riprovare con lo stesso UUID e il contenuto. Created distingue un nuovo commento da una retry. MailFailed segnala un problema di consegna mentre il commento rimane salvato.
Entrambi gli strumenti richiedono commenti da attivare per il progetto. Usano il proprietario attivo di una chiave di progetto personale e controllano i permessi attuali dell'oggetto. La pubblicazione richiede le scritture di progetto e la portata project.comments.add. REST utilizza POST /api/v1/operations/ztm_comment_read e POST /api/v1/operations/ztm_comment_add. Flusso di lavoro Web
Creare una retest da un run¶
Lo strumento MCP ztm_retest_create e il percorso REST POST /api/v1/operations/ztm_retest_create accettano gli stessi argomenti. Anteprima la selezione prima. Questo esempio include varianti non testate oltre a quelle fallite e bloccate.
{"mode":"preview","sourceRunId":36,"includeUntested":true}
Recensione RequestedCount, prerequisiti aggiuntivi (RequiredCount) e Errors. Utilizzare l'ambiente (Environment), un ID tester da Testers e ComparisonToken da questa anteprima. Sostituire i valori di esempio e generare un UUID fresco per ogni nuova richiesta. Se RequiresOldTemplate è vero, la creazione richiede un'approvazione esplicita con acceptOldTemplate: true.
{
"mode": "create",
"sourceRunId": 36,
"includeUntested": true,
"environment": "Staging",
"testerId": 7,
"comparisonToken": "<ComparisonToken>",
"creationId": "179e6928-a673-4dac-acae-b913914a13df"
}
La risposta contiene il nuovo testRunId di run non avviato. Se la connessione fallisce, riprovare la richiesta identica, inclusa la sua creationId. Entrambe le modalità richiedono l'attivazione delle scritture, l'ambito project.retest.create e le autorizzazioni di progetto e oggetti per visualizzare la sorgente e creare l'esecuzione. Si applicano anche le restrizioni demo. Utilizzo del cruscotto web.
Creare un problema da un risultato di prova¶
ztm_issue_create_from_result · POST /api/v1/operations/ztm_issue_create_from_result
Utilizzare lo strumento MCP o la relativa operazione REST corrispondente con l'ambito di scrittura personale project.defect.create. testCaseId è l'ID variante pianificato. Per i passaggi strutturati, le righe rapide e gli elementi di elenco, stepIndex inizia a zero. Omettere per risultati globali e testo non strutturato.
{"mode":"prepare","testRunId":40,"testCaseId":371,"stepKind":"structured","stepIndex":3}
Rivedere i campi restituiti e le opzioni di fissaggio. Dopo la conferma, utilizzare il RequestId restituito come requestId e inviare i valori prescelti e gli ID di collegamento dei risultati accessibili.
{"mode":"create","testRunId":40,"testCaseId":371,"requestId":"4c2ef7c8-b3a2-43e4-a721-6f04bb164b42","attachmentIds":[38]}
Dopo Retryable, riprovare con lo stesso ID una volta che il tracker è disponibile. Dopo Unknown, controllare il tracker e inviare il numero esistente come existingIssueReference. Dopo LinkPending, ripetere la richiesta di collegare il problema noto. Per incollare uno screenshot direttamente, utilizzare la finestra di dialogo web.