REST API¶
La nouvelle API HTTP/JSON expose les opérations commerciales du catalogue MCP sans enveloppe JSON-RPC. Les opérations disponibles dépendent de la version du serveur installé. Il s'agit d'une API orientée opération, et non d'une interface CRUD séparée pour chaque table de base de données.
Accès et autorisations¶
Envoyer une clé API MCP existante sous Authorization: Bearer <key>. Le MCP doit être activé à l'échelle mondiale et pour le projet. Les clés du projet nécessitent également X-ZTM-Project-UniqueId. Les clés mondiales nécessitent un accès explicite au projet pour les opérations du projet. Navigateur et Windows connexion ne remplacent pas une clé API.
Les permissions des utilisateurs, les portes d'écriture, les capacités autorisées et les restrictions de démo s'appliquent tout comme pour le MCP. Utilisez HTTPS en dehors des tests locaux. N'insérez jamais les clés dans les URL, le code source ou les journaux. Voir Mesures de sécurité et MCP.
Découvrez les opérations¶
| Demande | Résultat |
|---|---|
GET /api/v1/operations |
Opérations et contrats d'intrants à la disposition de la clé et du projet actuels |
GET /api/v1/operations/{operationId} |
Un contrat d'exploitation |
GET /api/v1/openapi.json |
OpenAPI 3.1 pour le même contexte d'autorisation |
POST /api/v1/operations/{operationId} |
Exécuter avec l'objet argument comme corps de requête |
POST /api/v1/resources/read |
Lire une ressource d'exportation liée à la clé |
OpenAPI contient un chemin POST en béton pour chaque opération disponible. Les entrées utilisent les mêmes schémas que MCP. La santé de la bibliothèque, la stabilité des résultats, les pièces jointes du projet et les comparaisons/snapshots de diffusion ont dactylographié des schémas de sortie. D'autres résultats dynamiques de requête/action conservent des contrats JSON extensibles. Le catalogue comprend des outils de requête et d'action partagés; tous les éléments du menu Web n'ont pas un point final dédié.
$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 '{}'
Ces variables d'environnement sont lues par le script d'appel PowerShell ; elles ne configurent pas automatiquement le serveur. Router les projets en utilisant des en-têtes, pas des arguments d'exploitation. Les corps JSON sont limités à 1 MIB et 32 niveaux de nidification. Les noms de propriété en double sont rejetés.
Lire le réglage d'aperçu de l'Office¶
Une clé globale de l'API MCP peut lire le mode XLSX efficace de l'installation avec POST /api/v1/operations/ztm_admin_office_preview_settings_get et le corps {}. Une réponse par exemple est {"xlsxPreviewMode":"HtmlTable"}; l'autre valeur possible est DevExpressPdf. Une clé de projet est insuffisante. Cette opération est en lecture seule. Utilisez administration du serveur pour modifier le réglage.
Écrits et exportations¶
Suivez l'aperçu de chaque opération et le contrat de commit explicite, par exemple ztm_project_action_prepare et ztm_project_action_commit. L'accès aux API ne remplace pas l'approbation des entreprises. Conservez les prévisualisations, les touches d'idemppotency et les commits liés au même contexte utilisateur et projet. Après un temps mort, vérifiez l'état de l'action plutôt que de répéter aveuglément une écriture.
Les exportations peuvent retourner un resourceUri. Lisez-le via POST /api/v1/resources/read avec {"uri":"<resourceUri>"} en utilisant la même clé et le même projet. La réponse contient contents avec des données texte ou Base64 et un type MIME. Les billets peuvent expirer ou permettre une lecture unique; traiter les URI de ressource comme confidentiels.
Erreurs¶
Les erreurs retournent le statut HTTP et application/problem+json contenant code et traceId : 400 entrées invalides, 401 authentification manquante/rejetée, 403 autorisations insuffisantes, 404 objets ou opérations non disponibles, 409 conflits d'action, 413 corps surdimensionnés, 415 types de contenu non pris en charge, 500 défaillances internes. Les conflits nécessitent un examen, et non des relevés automatiques. Donnez la prise en charge du traceId, jamais les clés ou les charges utiles confidentielles.
Règles prérequises et essais bloqués¶
ztm_project_query inclut rule pour la bibliothèque et les dépendances planifiées : 0 = Conseil seulement, 1 = Doit réussir, 2 = Doit ne pas avoir échoué.
Pour modifier une dépendance de bibliothèque existante, utilisez ztm_project_action_context, puis ztm_project_action_prepare avec capabilityId: project.test-case.dependency.set-rule et les arguments testCaseId, dependencyId, rule. Vérifiez l'aperçu et validez-le avec ztm_project_action_commit. La clé nécessite cette capacité d'écriture explicite. La création reste compatible : une nouvelle relation commence comme un indice ; sa règle peut alors être changée. Les plans et les exécutions existants ne sont pas synchronisés automatiquement.
POST /api/v1/operations/ztm_test_prerequisites_read avec {"plannedVariantId":123} évalue un test visible planifié. La réponse comprend isBlocked, needsRecheck et blockers. Les prédécesseurs invisibles ou manquants ne sont pas divulgués par leur nom; hasHiddenPrerequisites les indique. Cette évaluation ponctuelle n'accorde pas de droits d'exécution ou ne remplace pas la confirmation personnelle du test. La même opération est disponible par l'intermédiaire du MCP.
Pièces jointes du projet¶
ztm_project_attachments_read liste les pièces jointes du projet et leur ownerId, avec offset et limit (maximum 100). Offrez attachmentId pour télécharger contentBase64 (maximum 32 Mio). Un administrateur de projet actif ou un gestionnaire de projet est requis. Les fichiers liés dynamiquement sont listés mais ne peuvent pas être téléchargés par cette opération.
Les écritures nécessitent la capacité project.attachment.upload, project.attachment.update ou project.attachment.delete séparée. Les subventions de planification et d'attachement existantes ne permettent pas l'accès au dossier de projet. Utilisez le ownerId retourné, qui peut être 0 pour un projet.
- Télécharger : appelez
ztm_project_attachment_stageavectargetKind: "project",targetId: <ownerId>,fileName,mimeTypeetcontentBase64. La limite de mise en place actuelle est de 512 KiB par fichier. - Appelez
ztm_project_action_prepareavec la capacité, un nouveauidempotencyKeyetarguments. Télécharger les arguments :ownerKind: "project",ownerId,attachmentReferenceIddu ticket,displayNameetremarksen option. Mise à jour des métadonnées :ownerKind,ownerId,attachmentId,displayName,remarks. Supprimer :ownerKind,ownerId,attachmentId. - Passez en revue l'aperçu et confirmez par
ztm_project_action_commitavec la même clé. Les modifications simultanées provoquent un conflit; rejouer un commit réussi ne crée pas une autre pièce jointe.
Comparaisons et décisions de publication¶
ztm_release_snapshots_list liste les comparaisons lisibles enregistrées avec un filtre optionnel targetId. Passez le NextCursor retourné comme cursor pour lire la page suivante.
ztm_release_compare accepte les tableaux baseId, targetId, baseRunIds/targetRunIds explicites et baseScopeRunIds/targetScopeRunIds optionnels de { "runId": 123, "scopeRunId": 123 }. En option, baseSnapshotId/targetSnapshotId sélectionne les preuves enregistrées. Il retourne la comparaison Web incluant Fingerprint, en appliquant les mêmes règles de sélection et de permission d'objet.
Pour enregistrer des preuves, accorder explicitement project.release-review.snapshot-create et préparer/commettre des arguments query (l'objet de comparaison), name et fingerprint. Les changements de preuve sont rejetés. Lire la comparaison sauvegardée, decisionRevision et l'historique des décisions avec ztm_release_snapshot_read et snapshotId; historyBeforeRevision pages de décisions plus anciennes.
Une décision exige également project.release-review.decision-record, une autorisation de gestion de projet et une autorisation humaine explicite. Préparer accepte snapshotId, targetId, revision, outcome (1 accepté, 2 accepté avec conditions, 3 rejeté, 4 révoqué), responsibleUserId, comment, openPoints (un par ligne) et humanConfirmed: true. Le serveur enregistre l'acteur authentifié; le drapeau ne remplace pas l'approbation humaine réelle. Passez en revue l'aperçu, puis validez. Les règles du Web s'appliquent toujours : révision en cours, utilisateur responsable admissible, explication, portée complète et preuves inchangées. Les copies historiques des projets ne peuvent pas recevoir de nouvelle décision.
Couverture et limites¶
REST et MCP partagent leur catalogue d'exploitation. Cela n'implique pas une couverture complète de chaque fonctionnalité Web. Les pièces jointes au projet ont maintenant un contrat d'écriture distinct; les contrats d'essai, les exigences et la planification de téléchargement demeurent distincts. Les opérations reportées restent visibles dans le catalogue des capacités.
La présentation du navigateur, les dialogues fichier-picker et la connexion interactive n'ont pas besoin de paramètres de domaine séparés. La confirmation personnelle d'un nouveau test manuel n'est pas générée automatiquement pour le compte d'un testeur. Aperçu de la publication/PDF et les importations d'automatisation utilisent leurs opérations existantes; le transport REST n'étend pas leur champ d'application. La pièce jointe au projet écrit et les opérations de comparaison et de décision de publication sont maintenant disponibles comme décrit ci-dessus. Les chemins de serveur arbitraires et les liens de fichiers de Pont Local restent en dehors de ces opérations d'API. Les importations de fichiers de copies et de manifestes de variantes autonomes ne sont pas des actions distinctes dans l'implémentation Web examinée. Les sorties dactylographiées couvrent les pièces jointes au projet et les comparaisons/captures de sortie; les sorties dynamiques de requête/action existantes demeurent extensibles JSON, et ne sont pas entièrement dactylographiées.
Version des cas d'essai¶
Version de cas d'essai est disponible via POST /api/v1/operations/ztm_project_test_case_versions. Utilisez operation: "list", testCaseID et les options skip et take pour une liste délimitée avec la tête courante. read nécessite également revisionID, tandis que compare ajoute otherRevisionID; asset utilise revisionID et assetID et retourne les octets codés base64. restore-preview vérifie revisionID contre expectedHead.
Préparer la restauration par ztm_project_action_prepare, capacité project.test-case-version.restore, et les arguments testCaseID, revisionID, expectedHead, option note et options. Confirmez le jeton retourné via ztm_project_action_commit. options peut contenir explicitement des excludedAttributeIDs et flattenUnavailableReusableSteps exclus. Reliure de projet, identité active de l'utilisateur, permissions d'objet, champs d'écriture et protection de démo s'appliquent toujours. Ne jamais mettre les clés API dans des exemples, des journaux ou l'historique de shell.
Santé de la bibliothèque et stabilité des résultats¶
Ces opérations de lecture utilisent les mêmes services et les mêmes permissions d'objet que les rapports Web. Aucune subvention écrite n'est requise. Ils ne modifient pas, ne suppriment pas ou n'exécutent pas les tests.
| Fonctionnement | Filtres facultatifs |
|---|---|
ztm_library_health_read |
unitId incluant les descendants ou caseId; ageDays 1–36500 (par défaut 180); reason; page de 1; pageSize 1–100 (par défaut 50) |
ztm_test_stability_read |
testPlanId; testEnvironmentId (0 pour aucun environnement); fromUtc, toUtc en tant qu'horodatages UTC tels que 2026-11-08T12:00:00Z; lookbackRuns 1–200 (par défaut 50) |
Exemple : POST /api/v1/operations/ztm_library_health_read avec {"ageDays":180,"reason":"NoVisibleUsage","pageSize":25}. La réponse dactylographiée comprend Findings, CandidateCount, ScannedCaseCount, IsComplete, Limit, Page et PageSize. Les raisons sont NoVisibleUsage, NeverVisiblyExecuted, LongUnchanged, MissingTitle, MissingSteps, MissingExpectedResults, EmptyQuickContent et NoVariants. Les raisons peuvent se chevaucher. Aucune utilisation visible n'établit qu'un test n'est pas utilisé dans tout le projet; le contenu non modifié à long terme n'est pas automatiquement obsolète. L'analyse est limitée à 2000 cas visibles et 20000 utilisations visibles. Lorsque l'analyse de l'utilisation est incomplète, les indicateurs d'utilisation négatifs sont supprimés.
Exemple : POST /api/v1/operations/ztm_test_stability_read avec {"lookbackRuns":50}. La réponse comprend Series, FailureGroups, Evidence individuel et les nombres EligibleRuns, IncludedRuns, EligibleResults, IncludedResults, Truncated et InvalidEvidenceCount. Il utilise le résultat courant par run/cas/variant dans les runs finis visibles, et non l'historique complet de l'exécution. Au plus 20000 observations de résultats sont analysées. Les variations, les environnements et l'origine sont séparés; les différences de construction restent visibles. ContentDifferences et ContentFingerprint ne comparent que la description du cas d'essai enregistré, et non la spécification historique complète. Les changements de résultat sont des indicateurs, et non une preuve de flakiness. La correspondance du texte de défaillance ne prouve pas une cause partagée. Origin: 0 = automatisation de courant vérifiée, 1 = autre origine ou non vérifiée, 2 = preuve d'automatisation modifiée ou non valide.
Utilisez le boîtier d'entrée indiqué. Les plages non valides, les horodatages ou les filtres inconnus retournent 400; les objets de bibliothèque explicites illisibles retournent 403. Les mêmes outils et filtres sont disponibles dans le cadre du MCP.
Données de référence¶
Données de référence fournit des opérations dactylographiées pour les options de portée, listing, le contenu historique, la comparaison actuelle et les fichiers sauvegardés. Creation utilise prepar/commit avec la capacité project.library-baseline.create explicitement accordée; il n'y a pas d'opération de modification, de restauration ou de suppression. Voir le chapitre lié pour les noms d'outils, les arguments de portée, les règles de réessayer et la limite de 512 KiB pour les réponses de fichiers API.
Planification des statuts de l'arbre et des résultats personnalisés¶
ztm_project_planning_tree_read retourne l'arborescence de planification autorisée ainsi que les définitions de résultats disponibles et exécute les filtres. Exemple de demande :
{"resultDefinitionIds": [12, 15], "includeNoResult": true}
Utilisez les ID réels de resultDefinitions; les ID exemples sont des détenteurs de place. Les identifiants d'état utilisent OR; l'option treeFilterObjectId limite les exécutions. Les sélections rejetées ne signifient pas de filtre pour cette requête, indépendamment des préférences d'interface utilisateur sauvegardées. Le résultat suit les paramètres de visibilité arborescente de l'utilisateur et ne renvoie que les nœuds autorisés. Les ID explicites inconnus sont rejetés. L'opération de lecture ne modifie pas les préférences personnelles ni les résultats des tests. Le même contrat est disponible par l'intermédiaire du MCP.
Origine de la valeur de l'attribut¶
Pour les actions d'attribut existantes, ztm_project_action_context ajoute Metadata à PromotedFields et ObjectAttributes. Il comprend AttributeId, AttributeStyleFieldId, nom de champ, code et nom de style, type de champ, type de propriétaire et ID, Entail, et SourceKind (direct, inherited, default). Un défaut non enregistré n'a pas d'identifiant de propriétaire. Les définitions manquantes conservent leur ID de champ original alors que les détails de définition sont nuls.
Les mêmes informations sont disponibles par MCP et POST /api/v1/operations/ztm_project_action_context. Les permissions et les capacités de l'action d'attribut existante s'appliquent toujours; l'accès au contexte ne permet pas de lire davantage. Les champs de mot de passe sont exclus. Le contexte de lecture ne persiste pas. Attributs explique la différence entre l'héritage par nom et les champs promus.
Rétroaction sur les résultats visés¶
Les outils en lecture seule ztm_result_feedback_read, ztm_result_feedback_preview et ztm_result_feedback_export sont également disponibles en tant qu'opérations POST sous /api/v1/operations/. Chacun nécessite sa capacité de lecture project.result-feedback.read, .preview ou .export, plus un accès en lecture aux objets sélectionnés.
read accepte testRunId. preview ajoute resultItemIds (1 à 100 ID uniques), en option recipient, subject, message, externalReference et includeResultText (par défaut false). Sa réponse comprend le Fingerprint du contenu examiné. export utilise la même entrée plus expectedFingerprint, format (html ou xlsx) et en option language (de ou en). La réponse contient FileName, ContentType et ContentBase64.
Le contenu modifié nécessite un autre aperçu. Les résultats sélectionnés inaccessibles rejettent l'ensemble de la sortie ; il n'y a pas d'exportation partielle silencieuse. Aucune opération n'envoie de messages ou ne stocke de destinataires dans le projet. Voir Partager les résultats des essais pour les limites de flux et de contenu de l'utilisateur.
Règles relatives au rôle de la DA¶
ztm_ldap_role_rules_get lit les règles d'une configuration d'importation; ztm_ldap_role_rules_save les enregistre avec une révision attendue; ztm_ldap_role_rules_preview prévisualise les modifications d'adhésion. ztm_ldap_import_run exécute l'importation AD existante, y compris les règles sauvegardées. Les mêmes opérations sont disponibles en tant qu'outils MCP.
Tous les appels nécessitent configurationId. Enregistrer, prévisualiser et importer nécessite également expectedRevision à partir de la dernière réponse en lecture. Enregistrer accepte rules contenant des ID de règles stables, un état activé, un nom d'attribut, une valeur exacte, un rôle et un nom de groupe dédié. Les appelants ne choisissent pas les ID de groupe. Les contrats OpenAPI générés décrivent les champs complets.
Enregistrer et importer sont des écrits administratifs nécessitant une clé administrative activée avec l'accès au projet et la portée correspondante. Les autorisations d'administration du projet sont également vérifiées. Prévisualiser ne change pas d'adhésion mais a besoin d'accéder au répertoire configuré. La démo publique bloque ces appels de l'administration. Sur le conflit de révision, lire et revoir la configuration plutôt que de réessayer aveuglément une importation avec des paramètres dépassés.
Évaluations des défauts de fraîcheur et de libération manuelle¶
ztm_release_evidence_read, ztm_release_evidence_configure et ztm_release_evidence_observe lisent les limites d'âge ou stockent les limites et évaluent explicitement les défauts manuellement. Ils utilisent les contrats MCP correspondants et expectedRevision actuel. Relire après le conflit (409); ne pas répéter aveuglément. observe nécessite les referenceId et sourceFingerprint réels des report.EvidenceAssessment.Defects, plus state, criticality, observedUtc avec un fuseau horaire explicite et comment.
Les champs d'écriture dédiés sont project.release-evidence.configure et project.release-evidence.observe. Enabled projet écrit et les mêmes permissions de gestion des versions que Web s'appliquent également. Les déclarations comprennent l'utilisateur d'enregistrement et le temps; elles ne sont pas automatiquement vérifiées données tracker et ne doivent pas être inventées sans instruction humaine explicite. ztm_release_overview_read ajoute EvidenceAssessment pour de nouvelles captures en direct; le niveau assessment existant et les raisons l'intègrent. Les captures historiques demeurent inchangées. Voir Comparaison et acceptation des rejets.
Ensembles de données d ' essai structurés¶
Ces outils MCP sont également disponibles sous la forme de POST /api/v1/operations/<tool-name> avec les mêmes contrats. Voir Matrice de données d'essai pour les règles fonctionnelles.
Outil (préfixe ztm_test_data_set_) |
Arguments | Résultat |
|---|---|---|
list |
aucune | ensembles de données autorisés dans items |
read |
dataSetId |
ensemble de données avec révision et identifiants de ligne stables |
save |
data, expectedRevision, confirmed:true |
Ensemble de données persistantes avec une nouvelle révision |
delete |
dataSetId, expectedRevision, confirmed:true |
deleted:true; les données référencées restent protégées |
binding |
variantId |
binding ou null |
preview |
variantId, dataSetId, rowId |
textes, diagnostics et empreintes digitales sans changement |
apply |
arguments d'aperçu, expectedFingerprint, confirmed:true |
des textes contraignants et résolus |
unbind |
variantId, expectedFingerprint, confirmed:true |
unbound:true; les textes résolus sont conservés |
export |
dataSetId |
XLSX fileName, mimeType, contentBase64 |
import_preview |
dataSetId, expectedRevision, contentBase64 |
proposition non enregistrée; appeler explicitement save après |
Les champs de données sont Id, TestUnitId, Name, Revision, Columns et Rows; les lignes contiennent Id et Values. Création utilise le GUID zéro pour Id et un expectedRevision vide. Les lignes nécessitent des GUIDS uniques non nuls. Les mises à jour nécessitent la révision lue précédemment. Après les conflits, relisez et revoyez les changements.
Les quatre écritures nécessitent des champs individuels project.test-data-set.save, .delete, .apply ou .unbind, des écritures de projet activées et les permissions d'objets pertinentes. L'aperçu d'importation ne persiste jamais, mais nécessite la permission de modifier le propriétaire tout comme Web. Les restrictions de démonstration s'appliquent également par l'intermédiaire des API. REST utilise des clés au porteur plutôt que des cookies de navigateur et ne nécessite pas de jeton CSRF; les formulaires Web nécessitent toujours des jetons anti-forgery.
XLSX utilise une feuille de travail avec _RowId comme première colonne. Les formules, macros et références externes sont rejetées. Limites : 4 MiB XLSX, 16 MiB de contenu élargi, 30 colonnes de données, 1 000 lignes, 32 767 caractères par cellule et 2 MiB par ensemble de données. Uniquement enregistrer et importer prévisualiser accepter jusqu'à 6 MIB JSON transport y compris Base64; d'autres opérations conservent la limite 1-MiB existante.
binding retourne également des fixations congelées dont la source n'est pas disponible : SourceAvailable:false et SourceUnavailable diagnostique. Le texte sauvegardé reste lisible lorsque la variante est lisible. Le rafraîchissement nécessite l'accès à la source; sans liant utilise l'empreinte digitale de liaison actuelle.
Importation à partir d'un autre outil de test¶
Le développement actuel fournit POST /api/v1/operations/ztm_vendor_migration_preview et POST /api/v1/operations/ztm_vendor_migration_apply pour migration à partir d'un autre outil. Les outils MCP équivalents partagent ce contrat.
Fournir targetUnitId, sourceKey, workbookBase64 et en option attachmentsZipBase64.
Pour une table de fournisseurs, ajouter provider (testrail, xray, zéphyr, qase ou neutre) et fileName se terminant par .xlsx ou .csv. Continuez à envoyer les octets dans workbookBase64. Les colonnes détectées sont utilisées par défaut. Utilisez mapping pour assigner l'identifiant externe, le nom, le dossier, la description, les prérequis, les étapes, le résultat attendu et la pièce jointePath aux rubriques existantes. Utilisez la même source, le même fichier et le même mappage lors de l'application de l'aperçu. Les requêtes XLSX neutres sans ces champs conservent leur comportement existant.
Aperçu utilise la capacité de lecture project.vendor-migration.preview. Une clé de lecture du projet est suffisante; son utilisateur a également besoin d'une autorisation pour créer des cas dans la cible. Aucune portée d'écriture n'est requise pour l'aperçu. Il retourne Fingerprint, Items, Diagnostics et CanApply sans enregistrer. Appliquer uniquement lorsque CanApply est vrai; examiner un nouvel aperçu après les modifications.
Pour appliquer, envoyez les mêmes fichiers, l'empreinte de prévisualisation comme expectedFingerprint, un UUID frais comme operationId et confirmed: true. Réessayer la même opération avec le même UUID après une interruption du réseau.
L'application nécessite des actions d'écriture activées et la portée project.vendor-migration.apply. Les permissions d'objets et les restrictions de démo correspondent au flux de travail Web. La demande JSON incluant les données Base64 est limitée à 6 MB.
Lorsque la base de données du projet est occupée, REST retourne HTTP 503 avec DatabaseBusy et Retry-After: 2. MCP retourne actionErrorCode: "DatabaseBusy" et retryAfterSeconds: 2 dans les données d'erreur. Après la publication de l'accès, réessayez la même requête avec le même operationId ; les reçus sauvegardés sont retournés après avoir vérifié les permissions et le contenu actuel, sans en créer d'autres copies.
Remettre un essai¶
Utilisez une clé de projet personnelle avec la portée d'écriture project.test-run.handover pour lire les bénéficiaires admissibles et la révision en cours. MCP et REST utilisent les mêmes arguments.
- Appelez
ztm_project_action_contextavec{"capabilityId":"project.test-run.handover","itemKind":"test-run","itemId":23}. - Choisissez un ID de
Recipientset utilisezRevisioncommeexpectedRevision. Par exemple, appelezztm_run_handoverouPOST /api/v1/operations/ztm_run_handoveravec{"runId":23,"recipientUserId":7,"expectedRevision":0}.
Applied confirme que le transfert a été enregistré. mailStatus signale l'état de livraison (Sent, NotConfigured, MissingAddress, MissingLink ou Failed). Répéter la requête pour le destinataire actuel renvoie AlreadyApplied avec mailStatus: null. Lire à nouveau le contexte après un conflit (HTTP 409). Le propriétaire de la clé a besoin d'une autorisation pour modifier l'exécution. Les touches globales et les instances de démonstration ne peuvent pas effectuer des transferts.
Attribuer les cas d'essai prévus¶
- Utilisez
ztm_project_action_contextpour lire l'état courant de chaque exécution. Envoyez{"capabilityId":"project.test-run.assign","itemKind":"test-run","itemId":23}. Choisissez des cas à partir deCaseset un destinataire à partir deRecipients. - Appelez
ztm_run_assigndans MCP ou envoyezPOST /api/v1/operations/ztm_run_assign. Pour un cas non assigné, envoyez par exemple{"recipientUserId":7,"selection":[{"caseId":42,"runId":23,"expected":null}]}. Si le cas est déjà attribué, passez sesuserId,assignedUtcetassignedByUserIdsousexpected. PassezrecipientUserId: nullpour effacer l'affectation. - Lire la charge de travail par
ztm_run_workload_readouPOST /api/v1/operations/ztm_run_workload_readavec{"planId":9}.
L'écriture nécessite une clé personnelle avec la portée project.test-run.assign, exécutez l'autorisation d'édition et l'accès aux cas sélectionnés. Il est indisponible dans la démo publique. Sur le conflit, lisez à nouveau l'état actuel. Chaque requête enregistre sa sélection en une seule opération. La charge de travail ne comprend que les sorties ouvertes visibles.
Lire la couverture de la publication¶
- Appelez
ztm_coverage_matrix_readdans MCP ou envoyezPOST /api/v1/operations/ztm_coverage_matrix_readavec{}.Releasescontient les identifiants et les noms de la version visible. - Envoyez le
releaseIdsélectionné et éventuellementfilter. Par exemple,{"releaseId":"6bebaee0-20b9-4ff8-b4d1-abdd5d37833c","filter":"without-result"}. Les filtresall,without-test,without-resultetfailedcorrespondent à la vue du navigateur. - Lire
Rowspar exigence, cas d'essai et environnement.Statusest 0 pour aucun résultat, 1 pour non évaluable, 2 pour passé, 3 pour échec et 4 pour partiellement passé. Lorsque les preuves enregistrées sont visibles, les cellules comprennentResultItemId,RunTitle,RecordedUtcetTester.Totalscompte les exigences filtrées. Une exigence peut contribuer à plusieurs catégories.
Vous avez besoin d'une clé de projet personnelle et d'un accès en lecture aux données demandées. La fonction Exigences doit être activée pour le projet. Cette opération lit la matrice.
Créer et révoquer un lien de statut¶
Appelez ztm_share_link_create dans MCP ou POST /api/v1/operations/ztm_share_link_create dans REST. Tous deux acceptent le même corps JSON.
{"targetKind":"run","targetId":"23","validityDays":7,"requestId":"869744c5-8cdb-45e1-a300-918d308345f1","includeErrors":false,"includeFindings":false}
Définissez targetKind à run, plan ou release. Fournissez l'ID cible comme une chaîne, en utilisant son UUID pour une version. Choisissez 7 ou 30 jours. Les problèmes et les conclusions sont cachés par défaut. Ajouter recipientEmail pour envoyer le lien par courriel de projet.
Gardez shareId pour révocation. La réponse renvoie l'adresse du client dans url une fois, avec expiresUtc et mailStatus (NotRequested, Sent ou Failed). Résoudre une adresse client relative en fonction de l'origine du paramètre API. Traitez l'adresse, y compris son fragment, comme un mot de passe. Si la livraison échoue, le lien a déjà été créé. La réessayer avec le même requestId ne peut pas créer un autre lien ou envoyer un autre courriel. Si la réponse a été perdue, annuler l'entrée originale dans Liens partagés avant de créer un remplacement.
Reprise avec ztm_share_link_revoke ou POST /api/v1/operations/ztm_share_link_revoke et {"shareId":"<share UUID>"}. La réponse contient shareId et revokedUtc. La révocation répétée renvoie l'horodatage original.
Les deux actions nécessitent HTTPS (loopback est autorisé localement), des écritures de projet activées et une clé de projet personnelle avec la portée project.share-link.create ou project.share-link.revoke pertinente. Les permissions de cible et les restrictions de démo s'appliquent comme dans le client Web. Voir Accès aux clients.
Modifier plusieurs cas d'essai¶
Appelez ztm_library_bulk_update dans MCP ou POST /api/v1/operations/ztm_library_bulk_update. Par exemple, prévisualiser la configuration d'un attribut module :
{"operation":"preview","action":"attribute","caseIds":[12,31],"attributeName":"Modul","attributeValue":"Checkout"}
Vérifiez Rows. Ensuite, définissez operation à apply et soumettez les mêmes paramètres avec le Fingerprint retourné dans fingerprint. Ajouter un UUID dans requestId pour les relevés. Répéter la même requête avec cet ID retourne sa réception pendant que le serveur conserve la tâche. HTTP 409 nécessite un nouvel aperçu.
Utilisez targetUnitId avec move ou archive, reviewGroupId avec review et variantValueIds avec variant. Une destination d'archive doit être marquée comme unité d'archive. Chaque demande accepte jusqu'à 200 cas d'essai. Utilisez une clé de projet personnelle avec la portée project.test-library.bulk-update. Le serveur vérifie les droits actuels pour chaque cas. Les clés mondiales et l'accès de démonstration sont bloqués.
Utilisez {"operation":"undo","requestId":"<RequestId from receipt>"} avec la même clé de projet pour annuler les mouvements ou les changements d'attributs pendant que le travail reste dans la mémoire du serveur. Les autorisations et les changements intervenant sont à nouveau vérifiés.
Les arguments optionnels de boolean isArchive dans project.test-unit.update marquent une unité comme une archive. Utilisez le flux de prévisualisation/commit existant avec itemId et title. L'omission de isArchive préserve sa valeur. L'unité de connaissances du projet lit aussi exposer isArchive.
Rétester les résultats sélectionnés¶
ztm_library_retest ou POST /api/v1/operations/ztm_library_retest utilise le même workflow que Maintenez la bibliothèque de test :
- Envoyez
operation: "options"etfindingspour lire les sources autorisées, les environnements et les testeurs. Chaque découverte contientcaseId,plannedCaseIdouresultId; inclurevariantId,planIdetrunIdconnus. Choisissez explicitement un contexte lorsque plusieurs sont disponibles. - Envoyez
operation: "preview", la même sélection, etplanId,runId,environmentettesterId.Itemsénumère les variantes efficaces, y compris les conditions préalables obligatoires.Skippedidentifie les résultats exclus par son indice de sélection zéro. DéfiniracceptOldTemplate: trueseulement après avoir explicitement décidé d'utiliser des modèles périmés. - Envoyer
operation: "create"avec des entrées identiques, leFingerprintretourné sousfingerprintetRequestIdsousrequestId. Le reçu comprendRunId,Urlet les résultats manqués. Après une défaillance de connexion, reessayez le même ID de requête pour éviter de créer une seconde sortie.
Les prévisualisations expirent après 30 minutes et appartiennent au projet et à l'utilisateur. Les modifications apportées à la sélection, aux permissions ou au contenu nécessitent un nouvel aperçu. Chaque demande accepte au plus 200 résultats; une sortie de source existante est nécessaire. Le paramètre optionnel tab (health, impact, results) vérifie également que l'onglet correspondant est disponible.
Utilisez une clé de projet personnelle avec la portée d'écriture project.test-library.retest et la permission de créer des exécutions dans le plan sélectionné. Les touches d'administrateur global et le mode de démonstration public sont exclus. Les outils existants et la synchronisation par project.planned-test-case.synchronize-from-library demeurent inchangés.
Commentaires sur les objets¶
Utilisez ztm_comment_read pour lire les commentaires et l'activité pour un objet. Fournir kind (test-case, requirement, run, result) et id. Page offset et activityOffset indépendamment. Utilisez commentId pour localiser la page contenant un commentaire. Traiter le Markdown retourné comme contenu utilisateur.
ztm_comment_add enregistre markdown avec un UUID généré par le client sous commentId. Fournissez parentId pour répondre. Vous pouvez utiliser mentionUserIds pour informer les utilisateurs de projets explicitement sélectionnés avec un accès en lecture. Le texte doit inclure leur mention. Réessayez avec le même UUID et le même contenu. Created distingue un nouveau commentaire d'une réessayer. MailFailed signale un problème de livraison pendant que le commentaire reste sauvegardé.
Les deux outils exigent que les commentaires soient activés pour le projet. Ils utilisent le propriétaire actif d'une clé de projet personnelle et vérifient les permissions d'objets en cours. L'affichage nécessite l'écriture du projet et la portée project.comments.add. REST utilise POST /api/v1/operations/ztm_comment_read et POST /api/v1/operations/ztm_comment_add. Déroulement du Web
Créer un nouveau test à partir d'une course¶
L'outil MCP ztm_retest_create et la route REST POST /api/v1/operations/ztm_retest_create acceptent les mêmes arguments. Prévisualiser la sélection d'abord. Cet exemple inclut des variantes non testées en plus des variantes ratées et bloquées.
{"mode":"preview","sourceRunId":36,"includeUntested":true}
Examiner RequestedCount, conditions préalables supplémentaires (RequiredCount) et Errors. Utilisez l'environnement (Environment), un ID de testeur de Testers et le ComparisonToken de cet aperçu. Remplacer les valeurs de l'exemple et générer un UUID frais pour chaque nouvelle requête. Si RequiresOldTemplate est vrai, la création nécessite une approbation explicite avec acceptOldTemplate: true.
{
"mode": "create",
"sourceRunId": 36,
"includeUntested": true,
"environment": "Staging",
"testerId": 7,
"comparisonToken": "<ComparisonToken>",
"creationId": "179e6928-a673-4dac-acae-b913914a13df"
}
La réponse contient le nouveau testRunId de l'exécution non démarrée. Si la connexion échoue, réessayez la requête identique, y compris son creationId. Les deux modes exigent que les écritures soient activées, la portée project.retest.create et les autorisations de projet et d'objet pour afficher la source et créer l'exécution. Des restrictions de démonstration s'appliquent également. Utilisation du tableau de bord web.
Créer un problème à partir d'un résultat de test¶
ztm_issue_create_from_result · POST /api/v1/operations/ztm_issue_create_from_result
Utilisez l'outil MCP ou son fonctionnement REST correspondant avec la portée d'écriture personnelle project.defect.create. Le testCaseId est l'ID de la variante prévue. Pour les étapes structurées, les lignes rapides et les éléments de liste, stepIndex commence à zéro. Omettre pour les résultats globaux et le texte non structuré.
{"mode":"prepare","testRunId":40,"testCaseId":371,"stepKind":"structured","stepIndex":3}
Examinez les champs retournés et les options de pièce jointe. Après confirmation, utilisez le RequestId retourné comme requestId et envoyez les valeurs choisies et les ID de pièce jointe accessible.
{"mode":"create","testRunId":40,"testCaseId":371,"requestId":"4c2ef7c8-b3a2-43e4-a721-6f04bb164b42","attachmentIds":[38]}
Après Retryable, réessayez avec le même ID une fois que le tracker est disponible. Après Unknown, vérifiez le tracker et envoyez le numéro existant sous existingIssueReference. Après LinkPending, répétez la requête pour lier le problème connu. Pour coller une capture d'écran directement, utilisez la boîte de dialogue web.