--- title: "Migration vers l’importation et la resynchronisation de référence API asynchrone" slug: "migrate-to-async-api-reference-import-resync" updated: 2026-11-03T08:59:48Z published: 2026-11-03T08:59:48Z canonical: "docs.document360.com/migrate-to-async-api-reference-import-resync" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.document360.com/llms.txt > Use this file to discover all available pages before exploring further. # Migration vers l’importation et la resynchronisation de référence API asynchrone Si vous importez ou resynchronisez les API via l’API Client ou la `d360` CLI, vous devez déplacer votre intégration vers les nouveaux points de terminaison et commandes asynchrones avant que les anciens ne soient supprimés. Après la migration, de gros fichiers de spécification sont importés sans délai ni erreur mémoire, et votre pipeline obtient un résultat clair de réussite ou d’échec pour chaque importation. Ce guide vous guide dans la migration vers l’API client v3, l’API client v2 et la `d360` ligne de cli. IMPORTANT ! Sur l’API client V3, `force_import` il est désormais par `false` défaut sur toutes les routes d’importation et de resynchronisation, y compris les routes synchrones dépréciées. Si vos appels V3 omit `force_import`, une spécification qui importait auparavant malgré des erreurs ou des avertissements est maintenant refusée, même avant la migration. [Voir Décider comment gérer les résultats](/docs/fr/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings). --- ## Découvrez ce dont vous avez besoin pour migrer Commencez par l’intégration que vous utilisez aujourd’hui. Chaque ligne renvoie à la section dont vous avez besoin. | Si vous utilisez | Que faire | Aller à | | --- | --- | --- | | API client V3 (`/v3/projects/{projectId}/api-references`) | Remplacez les appels d’importation et de resynchronisation, et ajoutez le polling | [Migrer une intégration API client V3](/docs/fr/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v3-integration) | | Customer API v2 (`/v2/APIReferences`) | Remplacez les appels d’importation et de resynchronisation, et ajoutez le polling | [Migrer une intégration API client v2](/docs/fr/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v2-integration) | | Routes CI/CD (`/v2/apidocs/…`) appelées directement | Remplacez les itinéraires et ajoutez le sondage | [Migrer une intégration API client v2](/docs/fr/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v2-integration) | | `d360 apiref import` ou `d360 apiref resync` | Mettre à jour le CLI et passer à `d360 apiref submit` | [Migrer les pipelines CLI et CI/CD du d360](/docs/fr/migrate-to-async-api-reference-import-resync#migrate-the-d360-cli-and-cicd-pipelines) | | `d360 apidocs` ou `d360 apidocs:resync` | Mettre à jour le CLI et passer à `d360 apidocs:submit` | [Migrer les pipelines CLI et CI/CD du d360](/docs/fr/migrate-to-async-api-reference-import-resync#migrate-the-d360-cli-and-cicd-pipelines) | | Uniquement le portail de la base de connaissances | Rien. L’importation et la resynchronisation du portail ne sont pas affectées. | | Vos terminaux et commandes actuels fonctionnent toujours, mais ils sont obsolètes. NOTE Les anciens terminaux synchrones et les commandes CLI seront supprimés d’ici fin mars 2027. Planifiez votre migration avant cette fenêtre. --- ## Avant que tu commences Confirmez ce qui suit afin que votre premier appel asynchrone fonctionne : 1. **Votre clé ou rôle API V3 possède les deux permissions.** Soumettre **nécessite Mettre à jour les articles**. Lire le résultat nécessite **Voir les paramètres du projet**. Avec un seul d’entre eux, vous pouvez soumettre mais pas lire le résultat, ou inversement. Sur la v2, la même clé API CI/CD ou le même jeton API est utilisé pour soumettre et lire le résultat. 2. **Vous connaissez votre URL de base régionale.** | Région | Base URL | | --- | --- | | UE | `https://apihub.document360.io` | | États-Unis | `https://apihub.us.document360.io` | | Canada | `https://apihub.ca.document360.io` | | Hébergement privé | `https://apihub.<your-hosting-name>.document360.io` | 3. **Votre spécification est dans les limites de taille.** Une spécification peut atteindre jusqu’à 25 Mo, téléchargée ou récupérée à partir d’une URL. La requête de téléversement peut atteindre jusqu’à 26 Mo. Une récupération d’URL qui ne se termine pas en 100 secondes échoue. 4. **Vous avez décidé comment gérer les résultats.** Voir la section suivante. ### Décidez comment gérer les découvertes Lorsque l’importation forcée est désactivée, votre importation ou resynchronisation est refusée si la spécification suivante suit : - Y a une erreur ou un avertissement. - Aucune `servers` entrée. Force import est désactivé par défaut dans les trois intégrations : | Intégration | Par défaut | Qu’est-ce qui a changé | | --- | --- | --- | | API client V3 | `force_import: false` | Le défaut était `true`autrefois . Cela s’applique aux nouvelles routes V3 et aux routes V3 dépréciées. | | API client v2 | `forceImport=false` | Rien. Le défaut était déjà `false`. | | `d360` CLI | `--force-import` et `--force` sont hors service à moins que vous ne les dépassiez | Rien. | Lorsqu’une spécification est refusée, vous avez deux options : - **Corrigez la spécification.** C’est l’option recommandée. Les résultats peuvent affecter la documentation générée. Par exemple, une propriété typée `bool` au lieu de `boolean` est importée sans type. - **Force l’importation.** Envoyer `"force_import": true` (V3), `forceImport=true` (v2), `--force-import` (`apiref submit`), ou `--force` (`apidocs:submit`). Considérez cela comme un dérogation délibérée, pas comme un défaut. Si vos scripts V3 dépendaient de l’ancien défaut, ils sont refusés maintenant, que vous ayez migré ou non. Corrigez la spécification ou ajoutez `force_import: true`la spécification . La même confirmation s’applique à une resynchronisation qui supprimerait les points de terminaison. Sans cela, l’opération échoue avec un avertissement tel que *« Cette mise à jour supprimera définitivement 19 points de terminaison. Pass force_import=true pour confirmer »,* et liste les points de terminaison dans `result.deleted_endpoints`. Rien n’est supprimé tant que vous n’avez pas confirmé. --- ## Comment votre intégration évolue Aujourd’hui, votre appel attend que toute la spécification soit traitée et renvoie le résultat. Après la migration, votre intégration fonctionne en trois étapes : 1. **Soumettez** l’importation ou la resynchronisation. Vous obtenez `202 Accepted` immédiatement un ID d’opération. 2. **Interrogez** le point de terminaison d’état avec cet ID jusqu’à ce que l’opération atteigne un statut final. 3. **Lisez** le résultat, les erreurs, les avertissements et le nouvel identifiant de référence API de la réponse finale. Ce qui est importé ne change pas. La même spécification produit la même référence API. Seulement *lorsque* vous obtenez le résultat et *que l’endroit* où vous lisez les erreurs et avertissements changent. Un import typique se termine en quelques secondes à moins d’une minute. Ne considérez jamais la `202` réponse comme un succès. Les exemples JSON de ce guide sont résumés aux domaines qui comptent. --- ## Migrer une intégration API client V3 Authentifiez avec l’en-tête `X-API-Key: d360_sk_…` , ou un jeton porteur avec la `customerApi` lunette. ### Étape 1 : Remplacer les points d’extrémité | Fonctionnement | Ancien (déprécié) | Nouveau | | --- | --- | --- | | Importation | `POST /v3/projects/{projectId}/api-references` | `POST /v3/projects/{projectId}/api-references/imports` | | Resynchronisation | `PUT /v3/projects/{projectId}/api-references/{apiReferenceId}` | `POST /v3/projects/{projectId}/api-references/{apiReferenceId}/resyncs` | | Lisez le résultat | Dans la réponse | `GET /v3/projects/{projectId}/operations/{operationId}` | ### Étape 2 : Soumettre l’importation ou la resynchronisation Pour importer depuis une URL : ``` curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/imports" \ -H "X-API-Key: $D360_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.example.com/openapi.json", "workspace_id": "" }' ``` Pour importer depuis un fichier, envoyez `multipart/form-data`: ``` curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/imports" \ -H "X-API-Key: $D360_API_KEY" \ -F "file=@openapi.json;type=application/json" \ -F "workspace_id=" ``` Pour resynchroniser une référence d’API existante : ``` curl -i -X POST "https://apihub.document360.io/v3/projects/$PROJECT_ID/api-references/$API_REFERENCE_ID/resyncs" \ -H "X-API-Key: $D360_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.example.com/openapi.json" }' ``` Une resynchronisation ne prend `workspace_id`pas . Elle utilise l’espace de travail de la référence API existante. Utilisez ces champs de requête : | Terrain | Importation | Resynchronisation | Notes | | --- | --- | --- | --- | | `url` | Optionnel | Optionnel | Une URL de spécification accessible publiquement | | `file` | Optionnel (multi-parties) | Optionnel (multi-parties) | Le fichier de spécifications, JSON ou YAML | | `content` | Déprécié | Déprécié | Utilisez `file` à la place | | `workspace_id` | Obligatoire | Non utilisé | Espace de travail cible | | `publish_articles` | Optionnel | Optionnel | Publie les articles générés | | `user_id` | Requise avec `publish_articles` | Requise avec `publish_articles` | Le membre de l’équipe qui publie | | `force_import` | Optionnel, par défaut `false` | Optionnel, par défaut `false` | [Voir Décider comment gérer les résultats](/docs/fr/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings) | Fournissez exactement un de `url`, `file`, ou `content`. La réponse est `202 Accepted`. Sauvegardez le `operation_id` champ ou l’en-tête `Operation-Location` . Les deux identifient l’opération que vous interrogez ensuite. ``` Operation-Location: https://apihub.document360.io/v3/projects/{projectId}/operations/{operationId} ``` ``` { "data": { "id": null, "status": null, "operation_id": "4da2313e-b2da-440f-b4be-a1632901f2eb", "operation_status": "queued" }, "success": true } ``` NOTE Si votre intégration lit `data.id` ou `data.status` vient de la réponse de soumission, mettez-la à jour. Les deux sont `null` sur une `202` réponse car rien n’a encore été importé. Vous obtenez l’ID de référence API du résultat d’opération à l’étape 4. ### Étape 3 : Interroger jusqu’à la fin de l’opération ``` curl -sS "https://apihub.document360.io/v3/projects/$PROJECT_ID/operations/$OPERATION_ID" \ -H "X-API-Key: $D360_API_KEY" ``` Tant que l’opération est `queued` ou `running`, la réponse inclut un `Retry-After: 5` en-tête. Attendez autant de secondes entre les sondages. Arrêtez le sondage lorsque le statut est final : | Statut | Finale | Signification | | --- | --- | --- | | `queued` | Non | Accepté et en attente d’un employé | | `running` | Non | Traitement | | `succeeded` | Oui | Importé ou resynchronisé avec succès | | `failed` | Oui | Non appliqué. Vérifiez `message`, `errors`, et `result` | Limitez votre sondage par un temps mort. Vingt minutes sont généreuses pour la plupart des spécifications. Si une opération cesse de progresser, un agent de surveillance de fond la `failed`marque, afin que votre sondage atteigne toujours un statut final. ### Étape 4 : Lisez le résultat Lorsque l’opération réussit, enregistrez `result.api_definition_id`. C’est l’identifiant de référence API que vous utilisez lors des appels de resynchronisation, publication et suppression ultérieurs. ``` { "data": { "id": "4da2313e-b2da-440f-b4be-a1632901f2eb", "operation_type": "import-api-reference", "status": "succeeded", "message": null, "result": { "api_definition_id": "f9af5181-ee76-489d-b6c9-306e9eb6d60a", "is_success": true, "articles_created": 19, "categories_created": 3, "errors": null, "warnings": null, "is_server_available": true, "show_spec_file_warning": false, "deleted_endpoints": null }, "errors": null, "created_at": "2026-10-05T10:02:25.33Z", "updated_at": "2026-10-05T10:02:30.866Z", "completed_at": "2026-10-05T10:02:30.866Z" }, "success": true } ``` **Si votre spécification contient des résultats** et `force_import` est `false`, l’opération se termine comme `failed` et liste les résultats dans `result.errors` et `result.warnings`. Chacun `pointer` est un pointeur JSON vers votre spécification, vous pouvez donc aller directement à la ligne pour corriger. Le chemin dans cet exemple est illustratif. ``` { "data": { "status": "failed", "message": "The operation failed.", "result": { "is_success": false, "errors": [ { "message": "Invalid schema type identifier: bool", "pointer": "#/paths/~1orders/get/responses/200/content/application~1json/schema/properties/active/type" } ], "warnings": [] } } } ``` **Si la tâche ne pouvait pas s’exécuter**, par exemple parce que l’URL ne pouvait pas être récupérée, `message` et `errors[0].message` donner la raison : ``` { "data": { "status": "failed", "message": "This operation can't be completed. Please ensure that you have given a valid specification URL.", "result": null, "errors": [ { "code": "OPERATION_FAILED", "message": "This operation can't be completed. Please ensure that you have given a valid specification URL." } ] } } ``` ### Exemple : Faire un gate d’une étape pipeline sur le résultat d’importation Ce script soumet une importation, attend un statut final, puis sort avec un code non nul en cas d’échec : ``` #!/usr/bin/env bash set -euo pipefail BASE="https://apihub.document360.io" H=(-H "X-API-Key: $D360_API_KEY") # 1. Submit and capture the status URL from the Operation-Location header OP_URL=$(curl -sS -D - -o /dev/null -X POST \ "$BASE/v3/projects/$PROJECT_ID/api-references/imports" "${H[@]}" \ -H "Content-Type: application/json" \ -d "{\"url\":\"$SPEC_URL\",\"workspace_id\":\"$WORKSPACE_ID\"}" \ | awk 'tolower($1)=="operation-location:" {print $2}' | tr -d '\r') [ -n "$OP_URL" ] || { echo "Submission was not accepted" >&2; exit 1; } # 2. Poll until a final status (capped at 20 minutes) for _ in $(seq 1 240); do BODY=$(curl -sS "$OP_URL" "${H[@]}") STATUS=$(echo "$BODY" | jq -r '.data.status') case "$STATUS" in queued|running) sleep 5 ;; succeeded) echo "$BODY" | jq '.data.result'; exit 0 ;; *) echo "$BODY" | jq '.data.message, .data.result.errors, .data.result.warnings' >&2; exit 1 ;; esac done echo "Timed out waiting for the operation" >&2 exit 1 ``` --- ## Migrer une intégration API client v2 Authentifier avec l’en-tête`api_token`. Les extrémités asynchrones v2 prennent les mêmes `multipart/form-data` champs que les synchrones, y compris le .`forceImport` ### Étape 1 : Remplacer les points d’extrémité | Fonctionnement | Ancien (déprécié) | Nouveau | | --- | --- | --- | | Importation | `POST /v2/APIReferences` | `POST /v2/APIReferences/jobs` | | Resynchronisation | `PUT /v2/APIReferences` | `PUT /v2/APIReferences/jobs` | | Lisez le résultat | Dans la réponse | `GET /v2/APIReferences/jobs/{backgroundTaskId}` | Si vous appelez directement les routes CI/CD avec une clé API CI/CD, remplacez-les à la place. Les `d360 apidocs` commandes utilisent les mêmes routes. | Fonctionnement | Ancien (déprécié) | Nouveau | | --- | --- | --- | | Importation | `POST /v2/apidocs/import/{userId}` | `POST /v2/apidocs/jobs/import/{userId}` | | Resynchronisation | `POST /v2/apidocs/{apiDefinitionId}/resync/{userId}` | `POST /v2/apidocs/jobs/{apiDefinitionId}/resync/{userId}` | | Lisez le résultat | Dans la réponse | `GET /v2/apidocs/jobs/{backgroundTaskId}` | ### Étape 2 : Soumettre l’importation ou la resynchronisation Pour importer : ``` curl -i -X POST "https://apihub.document360.io/v2/APIReferences/jobs" \ -H "api_token: $D360_API_TOKEN" \ -F "url=https://api.example.com/openapi.json" \ -F "projectVersionId=" \ -F "userId=" \ -F "forceImport=false" ``` Pour resynchroniser : ``` curl -i -X PUT "https://apihub.document360.io/v2/APIReferences/jobs" \ -H "api_token: $D360_API_TOKEN" \ -F "url=https://api.example.com/openapi.json" \ -F "apiReferenceId=" \ -F "projectVersionId=" \ -F "userId=" \ -F "forceImport=false" ``` La réponse est `202 Accepted`. Sauf `background_task_id` pour les sondages. ``` { "data": { "background_task_id": "c02535d8-f051-41d3-92a9-57a224022f7d", "is_processing": true, "alerts": [{ "message": "Accepted for processing. Poll /v2/apireferences/jobs/c02535d8-… for the result." }] }, "success": true } ``` ### Étape 3 : Interroger jusqu’à la fin du travail ``` curl -sS "https://apihub.document360.io/v2/APIReferences/jobs/$BACKGROUND_TASK_ID" \ -H "api_token: $D360_API_TOKEN" ``` Continuez à sonder jusqu’à ce que `data.is_processing` soit `false`. ### Étape 4 : Lisez le résultat La réponse finale porte le résultat. Sauf `api_reference_id` pour les appels ultérieurs. ``` { "data": { "api_reference_id": "b8e74ec5-7de3-4d4b-8cbc-b2945f7aeb56", "articles_created": 19, "categories_created": 3, "errors": [], "alerts": [], "background_task_id": "c02535d8-f051-41d3-92a9-57a224022f7d", "is_processing": false }, "success": true } ``` Lisez les résultats de `data.errors`, et les avertissements de `data.alerts`. Pour une resynchronisation, `data.deleted_endpoints` liste les points de terminaison qui ont été supprimés, avec les `method`, `path`, `article_id`, et `title` de chacun. --- ## Migrer les pipelines CLI et CI/CD du d360 Le CLI a deux familles de commandes : V3 (`apiref`) et v2 (`apidocs`). Restez dans votre famille actuelle lors de la migration. Remplacez les commandes V3 par des commandes V3, et les commandes v2 par des commandes v2. ### Étape 1 : Mettre à jour le CLI Les nouvelles commandes nécessitent la **version 3.0.7** ou ultérieure. ``` npm install -g d360@latest d360 --version ``` Les anciennes commandes (`apiref import`, `apiref resync`, `apidocs`, `apidocs:resync`) sont marquées `[DEPRECATED]` dans `--help`. Elles cessent de fonctionner lorsque les points de terminaison qu’elles appellent sont supprimés. `d360 apidocs:validate` n’est pas obsolète. ### Étape 2 : Vérifiez que vous utilisez la bonne certification Les deux familles lisent le même `D360_API_KEY` nom de variable, mais chacune attend une identification différente. Utiliser la mauvaise est l’erreur de configuration la plus courante. La CLI vous indique quand elle détecte la mauvaise identifiante. | | Commandes v3 (`apiref`, `operations`) | commandes v2 (`apidocs`, `apidocs:submit`, `apidocs:status`) | | --- | --- | --- | | Diplôme | Une clé API V3 commençant par `d360_sk_`, créée sous **Paramètres** > **portail de la base de connaissances** > **clés API** | La clé API CI/CD du projet (un GUID) | | Envoyé comme | `X-API-Key` En-tête | `api_token` | | Besoins aussi | ID de projet (`--project-id` ou `d360 config set-project-id`), plus l’ID de l’espace de travail (importation) ou ID de référence API (resynchronisation) | ID utilisateur (`--userId`), plus l’ID de l’espace de travail (`--versionId`, import) ou l’ID de référence API (`--apiReferenceId`, resynchronisation). Pas d’ID de projet. | | Autorisations | **Mettre à jour les articles** pour soumettre, **voir les paramètres du projet** pour sonder. Une clé manquante peut soumettre sans lire le résultat, ou inversement. | La même clé est utilisée pour soumettre et être le statut | La ligne de commande n’a pas de connexion interactive. Elle prend la clé API de la première source qui est définie : un drapeau de commande, une variable d’environnement (`D360_API_KEY`, `D360_PROJECT_ID`, `D360_BASE_URL`), puis la configuration enregistrée (`d360 init`, ou `d360 config set-key` et `d360 config set-project-id`). Dans un pipeline, stockez la clé dans votre mémoire secrète CI et passez-la comme variable d’environnement. Utilisez l’URL de base de votre région. ### Étape 3 : Remplacez vos commandes #### Si vous utilisez les commandes V3 Remplacez les deux `apiref import` et `apiref resync` par `apiref submit`. L’ID que vous passez décide de l’opération : `--workspace-id` importe, `--api-reference-id` resynchronise. Avant : ``` d360 apiref import --workspace-id --url https://api.example.com/openapi.json d360 apiref resync --api-reference-id --url https://api.example.com/openapi.json ``` Après : ``` # Import a new API reference and wait for the result d360 apiref submit --workspace-id --url https://api.example.com/openapi.json --wait # Resync an existing API reference from a local file and wait d360 apiref submit --api-reference-id --file ./openapi.json --wait # Submit now and poll separately, for example from another pipeline stage id=$(d360 apiref submit --workspace-id --file ./openapi.json \ --filter operation_id -o tsv) d360 operations wait "$id" ``` Mettez à jour vos drapeaux : | | Ancien | Nouveau | | --- | --- | --- | | Importation ou resynchronisation | Deux commandes | Une commande : `--workspace-id` import, `--api-reference-id` resynchronise | | Source de la spécification | Import : `--url` ou `--content`. Resynchronisation : `--url` | `--url` ou `--file` pour les deux | | Publication après importation | `--publish-articles` | `--publish-articles` avec `--user-id` (obligatoire) | | Avertissements | | `--force-import` pour continuer les avertissements passés (désactivé par défaut) | | Résultat | Dans la réponse | `--wait`, ou `d360 operations wait <operation-id>` | Le `--filter` drapeau emprunte un chemin vers les données de réponse. Utilisez `operation_id`, non `data.operation_id`. L’option `-o tsv` affiche l’identifiant nu. `--wait` et `d360 operations wait` quittent `0` l’opération lorsque l’opération réussit. Ils quittent `1` quand elle échoue ou si le budget d’attente de 20 minutes est épuisé. Un délai budgétaire cesse d’attendre mais n’annule pas l’opération. #### Si vous utilisez des commandes v2 (apidocs) Ce sont les commandes affichées pour CI/CD dans les panneaux **de référence Ajouter une API** et **Modifier l’API** du portail. Remplacez les deux `apidocs` et `apidocs:resync` par `apidocs:submit`, puis lisez le résultat par `apidocs:status`. Les noms des drapeaux restent les mêmes (camelCase), et vous conservez la clé CI/CD. Avant : ``` d360 apidocs --apiKey "$D360_CICD_KEY" --userId --versionId \ --path ./openapi.json d360 apidocs:resync --apiKey "$D360_CICD_KEY" --userId \ --apiReferenceId --path ./openapi.json ``` Après : ``` # Import (prints the task ID on its own line) d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId --versionId \ --path ./openapi.json # Resync (passing --apiReferenceId makes it a resync) d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId \ --apiReferenceId --path ./openapi.json # Wait for the job to finish d360 apidocs:status --apiKey "$D360_CICD_KEY" --wait ``` `apidocs:submit` accepte les mêmes indicateurs que l’ancienne `apidocs` commande : `--apiKey`, `--userId`, `--versionId`, `--apiReferenceId`, `--path`, `--force`, , `--publish`, , et `--apihubUrl`. Elle affiche un identifiant de tâche et quitte la commande. `apidocs:status` ne prend que `--apiKey`, plus `--apihubUrl` pour les régions hors UE. Verrouillez toujours votre pipeline sur `--wait`. Sans cela, la commande rapporte une fois et sort `0` même si le travail est toujours en cours. Avec `--wait`, elle interroge jusqu’à la fin du travail, imprime les résultats (erreurs, alertes et tous les points de terminaison supprimés par une resynchronisation), et sort `1` si le travail n’a pas réussi. Si une resynchronisation supprime les points de terminaison, il s’arrête et les liste. Relance avec `--force` pour confirmer. ### Étape 4 : Mettez à jour votre pipeline Utilisez l’une de ces étapes GitHub Actions comme point de départ. Dans les deux, l’étape échoue lorsque la tâche échoue, et les résultats sont imprimés dans le journal. V3 : ``` - name: Publish API reference (V3) env: D360_API_KEY: ${{ secrets.D360_API_KEY }} # a d360_sk_ key D360_PROJECT_ID: ${{ vars.D360_PROJECT_ID }} run: | npm install -g d360@latest d360 apiref submit --api-reference-id "${{ vars.D360_API_REFERENCE_ID }}" \ --file ./openapi.json --wait ``` v2 (`apidocs`) : ``` - name: Publish API reference (v2) env: D360_CICD_KEY: ${{ secrets.D360_CICD_KEY }} # the project's CI/CD key run: | npm install -g d360@latest task=$(d360 apidocs:submit --apiKey "$D360_CICD_KEY" --userId "${{ vars.D360_USER_ID }}" \ --apiReferenceId "${{ vars.D360_API_REFERENCE_ID }}" --path ./openapi.json) d360 apidocs:status "$task" --apiKey "$D360_CICD_KEY" --wait ``` --- ## Corrigez les problèmes courants après la migration | Ce que tu vois | Pourquoi cela arrive | Que faire | | --- | --- | --- | | Résultats `403` de sondage après une soumission réussie | Votre clé ou votre rôle peut mettre à jour les articles mais ne peut pas consulter les paramètres du projet | Accordez à l’intégration les deux permissions | | Soumettre des déclarations `409 Conflict` | Une autre importation ou resynchronisation est déjà en cours d’exécution dans le projet. Un seul peut s’exécuter à la fois. | Interrogez la tâche en cours nommée dans la réponse, puis réessayez | | La resoumission renvoie le même ID d’opération | Tu as envoyé une demande identique alors que la première était encore en cours | Interrogez l’opération retournée. Aucune seconde importation n’est lancée. | | Une importation ou une resynchronisation V3 qui fonctionnait auparavant est maintenant refusée | `force_import` Il est désormais par défaut sur `false` toutes les routes V3, y compris celles dépréciées | Corrigez les résultats, ou fixez `force_import: true` délibérément. [Voyez Décidez comment gérer les résultats](/docs/fr/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings). | | Une resynchronisation échoue avec *« Cette mise à jour sera supprimée définitivement... »* | La resynchronisation supprimerait les points de terminaison | Examinez les points de terminaison listés, puis re-soumettez avec `force_import: true` (V3), `forceImport=true` (v2), `--force-import` (`apiref submit`) ou `--force` (`apidocs:submit`) pour confirmer | | Une soumission expire ou revient `5xx` | La demande a peut-être été acceptée ou non | Ne réessayez pas immédiatement. Une réévaluation peut lancer une seconde importation. Vérifiez s’il y a une opération en cours avec `GET /v3/projects/{projectId}/operations?status=running`, ou interrogez l’ID de l’opération si vous l’avez. | Le CLI suit la même règle de réessayage. Il ne réessaie pas une soumission après une `5xx` ou une connexion coupée. Il ne fait qu’essayer un `429`, qui est rejeté avant que tout travail ne commence. --- ## Vérifiez votre migration Votre migration est terminée lorsque : - Chaque appel d’importation et de resynchronisation utilise un point d’extrémité ou une commande asynchrone. - Votre intégration lit le résultat du point de terminaison d’état, pas de la `202` réponse. - Sur la version 3, votre intégration utilise `operation_id` la réponse de soumission au lieu de `data.id` et `data.status` de de. - Votre intégration se `409 Conflict` fait en attendant la tâche en cours et en réessayant. - Vous avez choisi comment gérer les résultats : corriger la spécification, ou fixer `force_import: true` délibérément. - Votre clé API ou votre rôle peut à la fois soumettre et lire des opérations. - Votre CLI est sur la version 3.0.7 ou ultérieure, et chaque famille utilise son propre identifiant : une `d360_sk_` clé pour `apiref`, et la clé CI/CD pour `apidocs`. - Votre pipeline échoue à l’étape lorsqu’une importation ou une resynchronisation échoue. - Vous avez terminé la migration avant que les anciens terminaux et commandes ne soient supprimés fin mars 2027. Application Programming Interface - A set of defined rules and protocols that allows one software application to communicate with and request functionality from another. APIs are the backbone of modern integrations. When Document360 connects to Slack, Intercom, or Google Analytics, it does so through their APIs. Document360 also provides its own REST API, enabling teams to programmatically manage articles, categories, and reader accounts from external systems.