--- title: "Migration zur asynchronen API-Referenz, Import und Resynchronisation" slug: "migrate-to-async-api-reference-import-resync" updated: 2026-11-03T08:59:55Z published: 2026-11-03T08:59:55Z 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 zur asynchronen API-Referenz, Import und Resynchronisation Wenn Sie API über die Customer API oder die `d360` CLI importieren oder neu synchronisieren, müssen Sie Ihre Integration auf die neuen asynchronen Endpunkte und Befehle verschieben, bevor die alten entfernt werden. Nach der Migration importieren große Spezifikationsdateien ohne Timeouts oder Speicherfehler, und Ihre Pipeline erhält bei jedem Import ein klares Bestehen oder Fehlschlagen. Dieser Leitfaden führt Sie durch die Migration von Customer API V3, Customer API v2 und der `d360` CLI. WICHTIG! In der Customer API V3 `force_import` ist `false` jetzt standardmäßig auf jeder Import- und Resync-Route, einschließlich der veralteten synchronen Routen. Wenn Ihre V3-Aufrufe weglassen `force_import`, wird eine Spezifikation, die früher trotz Fehler oder Warnungen importiert wurde, nun abgelehnt, noch bevor Sie migrieren. [Siehe Decide How to Handle Findings Sie](/docs/de/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings). --- ## Finde heraus, was du zum Migrieren brauchst Beginne mit der Integration, die du heute nutzt. Jede Zeile führt zu dem Abschnitt, den du brauchst. | Wenn du es benutzt | Was zu tun ist | Gehe zu | | --- | --- | --- | | Customer API V3 (`/v3/projects/{projectId}/api-references`) | Ersetze die Import- und Resync-Aufrufe und füge Polling hinzu | [Migration einer Customer API V3-Integration](/docs/de/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v3-integration) | | Customer API v2 (`/v2/APIReferences`) | Ersetze die Import- und Resync-Aufrufe und füge Polling hinzu | [Migration einer Customer API v2-Integration](/docs/de/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v2-integration) | | CI/CD-Routen (`/v2/apidocs/…`) werden direkt aufgerufen | Ersetze die Routen und füge Polling hinzu | [Migration einer Customer API v2-Integration](/docs/de/migrate-to-async-api-reference-import-resync#migrate-a-customer-api-v2-integration) | | `d360 apiref import` oder `d360 apiref resync` | Upgrade die CLI und Wechsel zu `d360 apiref submit` | [Migrieren Sie die d360 CLI- und CI/CD-Pipelines](/docs/de/migrate-to-async-api-reference-import-resync#migrate-the-d360-cli-and-cicd-pipelines) | | `d360 apidocs` oder `d360 apidocs:resync` | Upgrade die CLI und Wechsel zu `d360 apidocs:submit` | [Migrieren Sie die d360 CLI- und CI/CD-Pipelines](/docs/de/migrate-to-async-api-reference-import-resync#migrate-the-d360-cli-and-cicd-pipelines) | | Nur das Knowledge Base-Portal | Nichts. Portal-Import und Resync sind unbeeinflusst. | | Deine aktuellen Endpunkte und Befehle funktionieren weiterhin, sind aber veraltet. HINWEIS Die alten synchronen Endpunkte und CLI-Befehle werden bis Ende März 2027 entfernt. Planen Sie Ihre Migration vor diesem Zeitfenster. --- ## Bevor du anfängst Bestätigen Sie Folgendes, damit Ihr erster asynchroner Anruf funktioniert: 1. **Ihr V3-API-Schlüssel oder Ihre Rolle hat beide Berechtigungen. Das** Einreichen erfordert **Aktualisierungsartikel**. Das Lesen des Ergebnisses erfordert **Projekteinstellungen ansehen**. Mit nur einer davon können Sie das Ergebnis einreichen, aber nicht lesen, oder umgekehrt. In v2 wird derselbe CI/CD-API-Schlüssel oder API-Token verwendet, um das Ergebnis einzureichen und zu lesen. 2. **Du kennst deine regionale Basis-URL.** | Region | Basis-URL | | --- | --- | | EU | `https://apihub.document360.io` | | USA | `https://apihub.us.document360.io` | | Kanada | `https://apihub.ca.document360.io` | | Privates Hosting | `https://apihub.<your-hosting-name>.document360.io` | 3. **Ihre Spezifikation liegt innerhalb der Größenbegrenzung.** Eine Spezifikation kann bis zu 25 MB groß sein, hochgeladen oder von einer URL abgerufen. Die Upload-Anfrage kann bis zu 26 MB betragen. Ein URL-Abruf, der nicht innerhalb von 100 Sekunden abgeschlossen wird, schlägt fehl. 4. **Sie haben entschieden, wie Sie mit den Ergebnissen umgehen.** Siehe den nächsten Abschnitt. ### Entscheide, wie mit den Ergebnissen umgegangen werden soll Wenn der Zwangsimport deaktiviert ist, wird dein Import oder Neusynchronisieren abgelehnt, wenn die Spezifikation: - Gibt es irgendeinen Fehler oder eine Warnung. - Hat keinen `servers` Eingang. Der Zwangsimport ist in allen drei Integrationen standardmäßig deaktiviert: | Integration | Default | Was hat sich geändert | | --- | --- | --- | | Kunden-API V3 | `force_import: false` | Der Standard war `true`früher . Dies gilt für die neuen und die veralteten V3-Routen. | | Customer API v2 | `forceImport=false` | Nichts. Der Standard war bereits `false`. | | `d360` CLI | `--force-import` und `--force` sind los, es sei denn, du gehst an ihnen vorbei | Nichts. | Wenn eine Spezifikation abgelehnt wird, haben Sie zwei Möglichkeiten: - **Korrigiere die Spezifikation.** Dies ist die empfohlene Option. Ergebnisse können die generierte Dokumentation beeinflussen. Zum Beispiel wird eine Eigenschaft, die statt von `boolean` typisiert `bool` ist, ohne Typ importiert. - **Erzwingen Sie den Import.** Senden `"force_import": true` Sie (V3), `forceImport=true` (v2), `--force-import` (`apiref submit`), oder `--force` (`apidocs:submit`). Betrachten Sie dies als bewusste Überschreibung, nicht als Standard. Wenn deine V3-Skripte auf den alten Standard angewiesen sind, werden sie jetzt abgelehnt, egal ob du migriert hast oder nicht. Korrigiere die Spezifikation oder füge .`force_import: true` Die gleiche Bestätigung gilt für eine Neusynchronisation, die Endpunkte entfernen würde. Ohne sie schlägt die Operation mit einer Warnung wie *"Dieses Update löscht 19 Endpunkte dauerhaft aus. Übergebe force_import=wahr zum Bestätigen"* und listet die Endpunkte in `result.deleted_endpoints`auf. Nichts wird gelöscht, bis du bestätigt hast. --- ## Wie sich Ihre Integration verändert Heute wartet Ihr Anruf, bis die gesamte Spezifikation verarbeitet ist und das Ergebnis zurückgegeben wird. Nach der Migration funktioniert Ihre Integration in drei Schritten: 1. **Senden** Sie den Import ein oder synchronisieren Sie neu. Sie erhalten `202 Accepted` sofort eine Operations-ID. 2. **Abfrage** des Status-Endpunkts mit dieser ID, bis die Operation einen endgültigen Status erreicht. 3. **Lesen** Sie das Ergebnis, Fehler, Warnungen und die neue API-Referenz-ID aus der finalen Antwort. Was importiert wird, ändert sich nicht. Die gleiche Spezifikation erzeugt dieselbe API-Referenz. Nur *wenn* du das Ergebnis bekommst und *wo* du liest, ändern sich Fehler und Warnungen. Ein typischer Import ist in wenigen Sekunden bis unter einer Minute fertig. Behandle die Antwort `202` niemals als Erfolg. Die JSON-Beispiele in diesem Leitfaden sind auf die relevanten Felder gekürzt. --- ## Migration einer Customer API V3-Integration Authentifiziere dich mit dem `X-API-Key: d360_sk_…` Header oder einem Inhabertoken mit dem `customerApi` Scope. ### Schritt 1: Ersetzen Sie die Endpunkte | Betrieb | Alt (veraltet) | Neu | | --- | --- | --- | | Import | `POST /v3/projects/{projectId}/api-references` | `POST /v3/projects/{projectId}/api-references/imports` | | Resync | `PUT /v3/projects/{projectId}/api-references/{apiReferenceId}` | `POST /v3/projects/{projectId}/api-references/{apiReferenceId}/resyncs` | | Lesen Sie das Ergebnis | In der Antwort | `GET /v3/projects/{projectId}/operations/{operationId}` | ### Schritt 2: Den Import einreichen oder neu synchronisieren Um von einer URL zu importieren: ``` 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": "" }' ``` Um aus einer Datei zu importieren, senden `multipart/form-data`Sie : ``` 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=" ``` Um eine bestehende API-Referenz neu zu synchronisieren: ``` 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" }' ``` Eine Neusynchronisation nimmt `workspace_id`nicht . Sie verwendet den Arbeitsbereich der bestehenden API-Referenz. Verwenden Sie diese Anfragefelder: | Spielfeld | Import | Resync | Anmerkungen | | --- | --- | --- | --- | | `url` | Optional | Optional | Eine öffentlich erreichbare Spezifikations-URL | | `file` | Optional (mehrteilig) | Optional (mehrteilig) | Die Spezifikationsdatei, JSON oder YAML | | `content` | Veraltet | Veraltet | Stattdessen verwenden `file` | | `workspace_id` | Erforderlich | Nicht benutzt | Zielarbeitsbereich | | `publish_articles` | Optional | Optional | Veröffentlicht die generierten Artikel | | `user_id` | Erforderlich mit `publish_articles` | Erforderlich mit `publish_articles` | Das Teammitglied, das veröffentlicht | | `force_import` | Optional, standardmäßig `false` | Optional, standardmäßig `false` | [Siehe Entscheide, wie mit den Befunden umzugehen ist](/docs/de/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings) | Liefere genau eine von `url`, `file`, oder `content`. Die Antwort ist `202 Accepted`. Speichere das `operation_id` Feld oder den Header `Operation-Location` . Beide identifizieren die Operation, die du als Nächstes abrufst. ``` 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 } ``` HINWEIS Wenn deine Integration die Eingabeantwort liest `data.id` oder `data.status` es ist, aktualisiere sie. Beide sind `null` in einer `202` Antwort, weil noch nichts importiert wurde. Du bekommst die API-Referenz-ID aus dem Operationsergebnis in Schritt 4. ### Schritt 3: Umfragen, bis die Operation abgeschlossen ist ``` curl -sS "https://apihub.document360.io/v3/projects/$PROJECT_ID/operations/$OPERATION_ID" \ -H "X-API-Key: $D360_API_KEY" ``` Während die Operation oder `running`ist`queued`, enthält die Antwort einen Header`Retry-After: 5`. Warte so viele Sekunden zwischen den Umfragen. Stoppe das Abfragen, wenn der Status endgültig ist: | Status | Finale | Bedeutung | | --- | --- | --- | | `queued` | Nein | Akzeptiert und warte auf einen Mitarbeiter | | `running` | Nein | Bearbeitung | | `succeeded` | Ja | Erfolgreich importiert oder neu synchronisiert | | `failed` | Ja | Nicht angewendet. Prüfe `message`, `errors`, und `result` | Begrenzt deine Umfrage mit einer Auszeit. Zwanzig Minuten sind großzügig für die meisten Spezifikationen. Wenn eine Operation keinen Fortschritt macht, markiert ein Hintergrund-Watchdog sie `failed`, sodass deine Umfrage immer einen Endstatus erreicht. ### Schritt 4: Lesen Sie das Ergebnis Wenn die Operation erfolgreich ist, speichern `result.api_definition_id`Sie . Dies ist die API-Referenz-ID, die Sie bei späteren Resync-, Publish- und Delete-Aufrufen verwenden. ``` { "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 } ``` **Wenn Ihre Spezifikation Ergebnisse und** `force_import` ist`false`, endet die Operation mit `failed` und listet die Ergebnisse in und `result.warnings``result.errors` auf. Jede `pointer` Spezifikation ist ein JSON-Zeiger in Ihre Spezifikation, sodass Sie direkt zur Zeile zur Korrektur gehen können. Der Pfad in diesem Beispiel ist anschaulich. ``` { "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": [] } } } ``` **Wenn der Job nicht ausgeführt werden konnte**, zum Beispiel weil die URL nicht abgerufen werden konnte, `message` und `errors[0].message` gib den Grund an: ``` { "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." } ] } } ``` ### Beispiel: Gatet einen Pipeline-Schritt auf das Importergebnis Dieses Skript sendet einen Import, wartet auf einen Endstatus und verlässt bei einem Fehler einen von null verschiedenen Code: ``` #!/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 ``` --- ## Migration einer Customer API v2-Integration Authentifizieren Sie sich mit dem `api_token` Header. Die asynchronen Endpunkte v2 verwenden dieselben `multipart/form-data` Felder wie die synchronen, einschließlich der erforderlichen `forceImport`. ### Schritt 1: Ersetzen Sie die Endpunkte | Betrieb | Alt (veraltet) | Neu | | --- | --- | --- | | Import | `POST /v2/APIReferences` | `POST /v2/APIReferences/jobs` | | Resync | `PUT /v2/APIReferences` | `PUT /v2/APIReferences/jobs` | | Lesen Sie das Ergebnis | In der Antwort | `GET /v2/APIReferences/jobs/{backgroundTaskId}` | Wenn Sie die CI/CD-Routen direkt mit einem CI/CD-API-Schlüssel aufrufen, ersetzen Sie diese stattdessen. Die Befehle `d360 apidocs` verwenden dieselben Routen. | Betrieb | Alt (veraltet) | Neu | | --- | --- | --- | | Import | `POST /v2/apidocs/import/{userId}` | `POST /v2/apidocs/jobs/import/{userId}` | | Resync | `POST /v2/apidocs/{apiDefinitionId}/resync/{userId}` | `POST /v2/apidocs/jobs/{apiDefinitionId}/resync/{userId}` | | Lesen Sie das Ergebnis | In der Antwort | `GET /v2/apidocs/jobs/{backgroundTaskId}` | ### Schritt 2: Den Import einreichen oder neu synchronisieren Zum Import: ``` 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" ``` Zum Resynchronisieren: ``` 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" ``` Die Antwort lautet `202 Accepted`. Sparen `background_task_id` Sie die Umfragen. ``` { "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 } ``` ### Schritt 3: Umfragen, bis die Arbeit abgeschlossen ist ``` curl -sS "https://apihub.document360.io/v2/APIReferences/jobs/$BACKGROUND_TASK_ID" \ -H "api_token: $D360_API_TOKEN" ``` Weiter abfragen, bis `data.is_processing` .`false` ### Schritt 4: Lesen Sie das Ergebnis Die endgültige Antwort trägt das Ergebnis. Sparen Sie `api_reference_id` auf spätere Anrufe. ``` { "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 } ``` Lesen Sie die Ergebnisse von `data.errors`, und Warnungen von `data.alerts`. Für eine Neusynchronisation listet `data.deleted_endpoints` man die entfernten Endpunkte auf, mit dem `method`, `path`, `article_id`, und `title` von jedem. --- ## Migrieren Sie die d360 CLI- und CI/CD-Pipelines Die CLI hat zwei Befehlsfamilien: V3 (`apiref`) und v2 (`apidocs`). Bleib innerhalb deiner aktuellen Familie beim Migrieren. Ersetze V3-Befehle durch V3-Befehle und v2-Befehle durch v2-Befehle. ### Schritt 1: Upgrade der CLI Die neuen Befehle erfordern Version **3.0.7** oder neuer. ``` npm install -g d360@latest d360 --version ``` Die alten Befehle (`apiref import`, `apiref resync`, `apidocs`, ) `apidocs:resync`sind in `--help`markiert`[DEPRECATED]`. Sie hören auf zu funktionieren, wenn die von ihnen aufgerufenen Endpunkte entfernt werden.`d360 apidocs:validate` wird nicht veraltet. ### Schritt 2: Überprüfen Sie, ob Sie die richtige Qualifikation verwenden Beide Familien lesen denselben `D360_API_KEY` Variablennamen, erwarten aber jeweils eine andere Zugangsberechtigung. Die Verwendung der falschen ist der häufigste Einrichtungsfehler. Die CLI zeigt dir an, wenn sie die falsche Zugangsberechtigung erkennt. | | V3-Befehle (`apiref`, `operations`) | v2-Befehle (`apidocs`, `apidocs:submit`, `apidocs:status`) | | --- | --- | --- | | Qualifikation | Ein V3-API-Schlüssel, beginnend mit `d360_sk_`, **erstellt unter Settings** > **Knowledge Base Portal** > **API-Schlüssel** | Der CI/CD-API-Schlüssel des Projekts (ein GUID) | | Gesendet als | `X-API-Key` Überschrift | `api_token` | | Außerdem benötigt es | Projekt-ID (`--project-id` oder `d360 config set-project-id`), plus die Arbeitsbereichs-ID (Import) oder API-Referenz-ID (Resync) | Benutzer-ID (`--userId`), plus die Arbeitsbereichs-ID (`--versionId`, import) oder API-Referenz-ID (`--apiReferenceId`, resync). Keine Projekt-ID. | | Berechtigungen | Artikel **aktualisieren**, um einzureichen, **und die Projekteinstellungen zur Abfrage ansehen**. Ein fehlender Schlüssel kann entweder das Ergebnis einreichen, aber nicht lesen, oder umgekehrt. | Der gleiche Schlüssel wird für Senden und Status verwendet | Die CLI hat keinen interaktiven Login. Sie nimmt den API-Schlüssel aus der zuerst gesetzten Quelle: ein Befehlsflag, eine Umgebungsvariable (`D360_API_KEY`, `D360_PROJECT_ID`, `D360_BASE_URL`), dann die gespeicherte Konfiguration (`d360 init`, oder `d360 config set-key` und `d360 config set-project-id`). In einer Pipeline speichern Sie den Schlüssel in Ihrem CI-Geheimspeicher und geben Sie ihn als Umgebungsvariable weiter. Verwenden Sie die Basis-URL für Ihre Region. ### Schritt 3: Ersetze deine Befehle #### Wenn du V3-Befehle benutzt Ersetze beide `apiref import` und `apiref resync` durch `apiref submit`. Die von dir übergebene ID entscheidet über die Operation: `--workspace-id` importiert, `--api-reference-id` synchronisiert neu. Vorher: ``` 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 ``` Nach: ``` # 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" ``` Aktualisieren Sie Ihre Flaggen: | | Alt | Neu | | --- | --- | --- | | Importieren oder neu synchronisieren | Zwei Befehle | Ein Befehl: `--workspace-id` importiert, `--api-reference-id` synchronisiert neu | | Spezifikationsquelle | Import: `--url` oder `--content`. Resync: `--url` | `--url` oder `--file` für beide | | Veröffentlichen nach dem Import | `--publish-articles` | `--publish-articles` mit `--user-id` (erforderlich) | | Warnungen | | `--force-import` Um die vergangenen Warnungen fortzusetzen (standardmäßig ausgeschaltet) | | Ergebnis | In der Antwort | `--wait`, oder `d360 operations wait <operation-id>` | Die Flagge `--filter` nimmt einen Pfad in die Antwortdaten. Verwenden `operation_id`Sie , nicht `data.operation_id`. Die `-o tsv` Option druckt die nackte ID aus. `--wait` und `d360 operations wait` verlassen, `0` wenn die Operation erfolgreich ist. Sie verlassen, `1` wenn sie scheitert oder das 20-minütige Wartebudget abgelaufen ist. Eine Budget-Auszeit beendet das Warten, aber die Operation wird nicht abgebrochen. #### Wenn du v2 (apidocs) Befehle verwendest Dies sind die Befehle, die für CI/CD in den **API-Referenzpanels hinzufügen** und **API-Bearbeiten des Portals** angezeigt werden. Ersetzen Sie beide `apidocs` durch `apidocs:submit``apidocs:resync` und lesen Sie das Ergebnis mit `apidocs:status`. Die Flag-Namen bleiben gleich (camelCase), und Sie behalten den CI/CD-Schlüssel. Vorher: ``` d360 apidocs --apiKey "$D360_CICD_KEY" --userId --versionId \ --path ./openapi.json d360 apidocs:resync --apiKey "$D360_CICD_KEY" --userId \ --apiReferenceId --path ./openapi.json ``` Nach: ``` # 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`akzeptiert die gleichen Flags wie der alte `apidocs` Befehl: `--apiKey`, `--userId`, , `--versionId`, `--apiReferenceId`, `--publish``--path``--force`und `--apihubUrl`. Es druckt eine Task-ID aus und verlässt es. `apidocs:status` nimmt nur `--apiKey`, plus `--apihubUrl` für Nicht-EU-Regionen. Sperre deine Pipeline immer auf `--wait`. Ohne sie meldet der Befehl einmal und verlässt `0` den Job, selbst wenn der Job noch läuft. Mit `--wait`, pollt er ab, bis der Job abgeschlossen ist, druckt die Ergebnisse (Fehler, Warnungen und alle durch eine Neusynchronisierung entfernten Endpunkte aus und verlässt `1` es, wenn der Job nicht erfolgreich war. Wenn eine Neusynchronisation Endpunkte löschen würde, stoppt es und listet sie auf. Führe mit erneut aus `--force` , um es zu bestätigen. ### Schritt 4: Aktualisieren Sie Ihre Pipeline Nutzen Sie einen dieser GitHub-Aktionsschritte als Ausgangspunkt. In beiden Fällen scheitert der Schritt, wenn der Job fehlschlägt, und die Ergebnisse werden im Logbuch veröffentlicht. 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 ``` --- ## Beheben Sie häufige Probleme nach der Migration | Was du siehst | Warum es passiert | Was zu tun ist | | --- | --- | --- | | Die Umfrageergebnisse kommen nach erfolgreicher Einreichung zurück `403` | Dein Schlüssel oder deine Rolle kann Artikel aktualisieren, aber keine Projekteinstellungen anzeigen | Gib der Integration beide Berechtigungen | | Steuererklärungen einreichen `409 Conflict` | Ein weiterer Import oder Resync läuft bereits im Projekt. Es kann immer nur einer gleichzeitig laufen. | Abfrage der laufenden Aufgabe in der Antwort und Versuche es dann erneut | | Das erneute Einreichen ergibt dieselbe Operations-ID zurück | Du hast eine identische Anfrage geschickt, während die erste noch lief | Abfrage der zurückgegebenen Operation. Kein zweiter Import wird gestartet. | | Ein V3-Import oder Resync, der früher funktionierte, wird jetzt abgelehnt | `force_import` jetzt standardmäßig auf `false` allen V3-Routen, einschließlich der veralteten | Beheben Sie die Ergebnisse oder setzen Sie gezielt ein. `force_import: true` [Siehe Entscheiden, wie Sie mit Ergebnissen umgehen](/docs/de/migrate-to-async-api-reference-import-resync#decide-how-to-handle-findings). | | Eine Neusynchronisation schlägt fehl mit *"Dieses Update wird dauerhaft gelöscht..."* | Die Neusynchronisation würde Endpunkte entfernen | Überprüfen Sie die angegebenen Endpunkte und senden Sie dann erneut mit `force_import: true` (V3), `forceImport=true` (v2), `--force-import` (`apiref submit`) oder `--force` (`apidocs:submit`) ein, um zu bestätigen | | Eine Abgabe läuft zeitlich ab oder wird zurückgegeben `5xx` | Der Antrag wurde möglicherweise angenommen oder auch nicht | Versuchen Sie es nicht sofort erneut. Ein erneuter Versuch kann einen zweiten Import starten. Prüfen Sie eine laufende Operation mit `GET /v3/projects/{projectId}/operations?status=running`, oder prüfen Sie die Operations-ID, falls Sie sie haben. | Die CLI folgt derselben Retry-Regel. Sie versucht keine Absendung nach einer `5xx` oder einer abgebrochenen Verbindung erneut. Sie versucht nur eine `429`, die abgelehnt wird, bevor die Arbeit beginnt. --- ## Überprüfe deine Migration Ihre Migration ist abgeschlossen, wenn: - Jeder Import- und Resync-Aufruf verwendet einen asynchronen Endpunkt oder Befehl. - Deine Integration liest das Ergebnis vom Statusendpunkt, nicht von der Antwort `202` . - In V3 verwendet `operation_id` deine Integration statt und `data.id` `data.status` aus der Send-Antwort. - Deine Integration regelt `409 Conflict` das, indem du auf die laufende Aufgabe wartest und es erneut versuchst. - Du hast gewählt, wie du mit den Ergebnissen umgehst: die Spezifikation korrigieren oder gezielt einstellen `force_import: true` . - Dein API-Schlüssel oder deine Rolle kann sowohl Operationen senden als auch lesen. - Ihre CLI ist auf Version 3.0.7 oder neuer, und jede Familie verwendet ihre eigene Zugangsberechtigung: einen `d360_sk_` Schlüssel für `apiref`, und den CI/CD-Schlüssel für `apidocs`. - Deine Pipeline scheitert im Schritt, wenn ein Import oder Resync fehlschlägt. - Sie haben die Migration abgeschlossen, bevor die alten Endpunkte und Befehle Ende März 2027 entfernt werden. 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.