Dateien in einer API identifizieren – ohne sich auf veränderliche Namen oder Pfade zu verlassen

Warum Name oder Pfad eine Integration stören können

Den vollständigen Pfad als Schlüssel zu verwenden, wirkt einfach: Damit lässt sich eine Datei finden, und in Protokollen ist er leicht zu lesen. Ein Pfad beschreibt jedoch, wo sich eine Ressource befindet, nicht unbedingt, um welche Ressource es sich handelt. Wenn jemand Ordner neu organisiert oder den Namen ändert, kann eine in einem anderen System gespeicherte Referenz ins Leere laufen. Ein Synchronisierungsprozess könnte die Änderung dann als Verschwinden einer Datei und Auftauchen einer anderen interpretieren.

Der Name allein ist noch mehrdeutiger: Verschiedene Dateien können gleich heißen, und ein Name kann sich durch eine Korrektur, eine neue Konvention oder eine Benutzeraktion ändern. Geh nicht davon aus, dass eine API die Identität beim Verschieben oder Umbenennen erhält. Die von Microsoft dokumentierte Umbenennungsoperation für Azure Storage unter https://learn.microsoft.com/es-es/rest/api/storageservices/rename-file ermöglicht eine Namensänderung. Daraus geht jedoch nicht automatisch hervor, welche Identitätsgarantien ein beliebiger Dienst bietet. Das muss für den konkreten Vertrag geprüft werden.

• Behandle Namen und Pfade als beschreibende Attribute, die sich ändern können.
• Stelle vor der Synchronisierung fest, welche Ressource aktualisiert wird und anhand welcher Signale sie erkannt werden kann.

Name, Pfad und Identifikatoren getrennt behandeln

Im Integrationsmodell sollten vier Begriffe unterschieden werden. Der sichtbare Name ist die Bezeichnung der Datei; der Pfad beschreibt ihren Speicherort innerhalb einer Struktur; der Ressourcenidentifikator ist der von der API dokumentierte Wert, mit dem auf die Ressource verwiesen wird; und der externe Identifikator wird von einem anderen System verwendet, etwa einem Geschäftssystem oder einer Clientanwendung. Allein die Bezeichnung eines Felds als id belegt ohne Dokumentation weder seinen Geltungsbereich noch seine Gültigkeitsdauer.

Manche Identifikatoren gelten möglicherweise nur innerhalb eines Kontos, Arbeitsbereichs oder Dienstes. Ein interner Schlüssel für deine Integration kann deshalb aus Anbieter, Kontobereich und dokumentiertem Identifikator bestehen, statt vorauszusetzen, dass der Wert global eindeutig ist. Speichere Name und Pfad als zusätzliche Daten zum Anzeigen, Suchen oder zur Diagnose. Verwende sie nicht als Identität, wenn der Dienst nicht garantiert, dass sie eindeutig und unveränderlich sind.

• Kläre, innerhalb welchen Bereichs der Identifikator eindeutig ist und was beim Verschieben, Kopieren oder Neuerstellen der Datei geschieht.
• Unterscheide eine Kopie derselben Ressource von einer neuen Version; setze nicht voraus, wie die API diese definiert.

OpenAPI für jede Operation einzeln prüfen

Beginne mit der OpenAPI-Spezifikation für die Version, die deine Integration tatsächlich verwendet. Suche nach Operationen zum Auflisten, Abrufen, Erstellen, Aktualisieren, Verschieben und Löschen, sofern es sie gibt. Prüfe bei jeder Operation die Pfad- und Abfrageparameter, den Anfragekörper, die Antworten und wiederverwendeten Schemas. Notiere den Namen und Typ jedes möglichen Identifikatorfelds, wo es vorkommt und ob es in einer Erstellungsantwort zurückgegeben wird. Leite das Verhalten eines Endpunkts nicht allein aus dem Feldnamen ab.

Vergleiche den Vertrag anschließend mit der begleitenden Dokumentation und in einer Testumgebung mit echten Antworten, die keine sensiblen Daten enthalten. Prüfe, ob eine Operation einen Identifikator oder einen Pfad erwartet, ob sie beides zurückgibt und ob Suchvorgänge Filter unterstützen. Google Drive dokumentiert unter https://developers.google.com/workspace/drive/api/guides/search-files?hl=es-419 mehrere Möglichkeiten, nach Dateien und Ordnern zu suchen, und erwähnt die Methode list. Daraus lassen sich die Felder oder Garantien eines anderen Dienstes nicht verallgemeinern. Apification bietet Integration über REST API und OpenAPI; Identitätsgarantien müssen jedoch in der Dokumentation der jeweiligen Operation bestätigt werden.

• Halte die Spezifikationsversion, Operation, Feld, Typ, Geltungsbereich und Verhaltensnachweise fest.
• Wenn der Vertrag Stabilität oder Lebenszyklus nicht dokumentiert, kennzeichne die Garantie als unbekannt und frage beim Anbieter nach.

Eine explizite Zuordnungstabelle führen

Nachdem du den von der API bereitgestellten Identifikator bestätigt hast, speichere eine Zuordnung zwischen dem Geltungsbereich des Dienstes, diesem Identifikator und der Referenz des externen Systems. Ergänze bei Bedarf den beobachteten Namen und Pfad, den Synchronisierungsstatus und den Zeitpunkt der letzten Prüfung. Diese Metadaten helfen bei der Diagnose eines Konflikts, sollten aber nicht den Primärschlüssel ersetzen. Lege außerdem fest, welches System Änderungen an den einzelnen Attributen vornehmen darf. Wenn beide Seiten dieselbe Datei umbenennen können, muss vereinbart werden, wie Abweichungen aufgelöst werden.

Aktualisiere den Eintrag erst nach einer bestätigten Antwort auf eine Erstellungs- oder Änderungsoperation, nicht bereits beim Absenden der Anfrage. Schlägt eine Operation fehl oder ist ihr Ergebnis wegen eines Verbindungsabbruchs ungewiss, markiere die Zuordnung für einen Abgleich, statt automatisch eine weitere Datei anzulegen. Gestalte Wiederholungen von Aufgaben so, dass sie keine doppelten Zuordnungen erzeugen. Wenn du Webhooks empfängst, prüfe, welches Ereignis der Vertrag beschreibt, und gleiche den Status ab, bevor du die Zuordnung änderst.

• Speichere nur die notwendigen Nachweise, um die Zuordnung prüfen zu können; lege keine Anmeldedaten oder Geheimnisse daneben ab.
• Definiere je nach Bedarf deiner Integration Statuswerte wie ausstehend, aktuell, nicht gefunden und muss geprüft werden.

Umbenennungen, Verschiebungen und den Lebenszyklus testen

Bereite einen kontrollierten Test mit einer Referenzdatei vor und protokolliere ihren Identifikator, Namen, Pfad und die Antwort auf eine Abfrage. Benenne sie mit der dokumentierten Operation oder dem vorgesehenen Ablauf um, rufe sie erneut ab und vergleiche die Felder. Wiederhole den Test mit einer Verschiebung zwischen Speicherorten, falls der Dienst dies unterstützt. Ziel ist nicht, zu bestätigen, was geschehen sollte, sondern zu beobachten, was tatsächlich geschieht, und das Ergebnis mit einer schriftlich festgehaltenen Garantie abzugleichen. Behalte während des Tests denselben externen Eintrag bei, damit du erkennen kannst, ob deine Integration ihn dupliziert.

Teste auch das Löschen und Neuerstellen mit demselben Namen und Speicherort. Prüfe, ob die Suche die vorherige Ressource, eine neue, keine oder mehrere Ressourcen zurückgibt und welcher Fehler beim Abruf der gelöschten Referenz auftritt. Verwende eine Zuordnung nicht automatisch wieder, nur weil der Pfad übereinstimmt. Stelle sicher, dass die Tests verspätete Antworten, Zwischenfehler und Wiederholungsversuche abdecken, und bewahre genügend Ergebnisse auf, um die Diagnose nachvollziehen zu können.

• Mindestfälle: umbenennen, verschieben, löschen, mit gleichem Namen neu erstellen und eine unterbrochene Operation wiederholen.
• Abnahmekriterium: Die externe Zuordnung verweist auf die richtige Ressource und erzeugt weder Duplikate noch unbemerkte neue Zuordnungen.

Wenn kein stabiler Identifikator dokumentiert ist

Wenn die Spezifikation keinen Identifikator bereitstellt oder dessen Stabilität nicht dokumentiert, erfinde keine Garantie. Frage den Anbieter nach dem kanonischen Identifikator, seinem Geltungsbereich und den Regeln für Umbenennen, Verschieben, Kopieren und Neuerstellen. Bis dahin kannst du mehrere Signale verwenden, um mögliche Treffer zu finden – zum Beispiel Pfad, Name und vom Dienst bereitgestellte Attribute. Behandle das Ergebnis jedoch als vorläufigen Treffer, nicht als nachgewiesene Identität.

Bei mehrdeutigen Fällen solltest du die automatische Aktualisierung stoppen und den Eintrag zur Prüfung oder zum Abgleich weiterleiten. Allein Name und Größe zu vergleichen, könnte beispielsweise zwei legitime Dateien verwechseln; auch ein Inhalts-Hash hat Grenzen und ersetzt nicht die Identität der Ressource. Die File System Access API unter https://developer.chrome.com/docs/capabilities/web-apis/file-system-access?hl=es-419 ermöglicht Webanwendungen die Interaktion mit Dateien auf dem Gerät des Nutzers. Daraus geht jedoch nicht hervor, welche Identität ein Remote-Speicherdienst bereitstellt. Mach die Unsicherheit ausdrücklich kenntlich.

• Verwende ungefähre Treffer nur als Unterstützung für eine Prüfung, niemals für eine unbemerkte neue Zuordnung.
• Dokumentiere, welche Änderungen einen manuellen Eingriff erfordern und welche Daten zur Klärung benötigt werden.

Checkliste vor der Bereitstellung

Prüfe vor der Aktivierung einer Synchronisierung, ob das Team erklären kann, woher der Identifikator stammt, in welchem Geltungsbereich er gültig ist und welche Operation ihn zurückgibt. Stelle sicher, dass die Zuordnungstabelle Identität von veränderbaren Attributen trennt, eine fehlgeschlagene Antwort nicht mit einer Löschung verwechselt wird und unbestätigte Änderungen abgeglichen werden können. Mit Apification kannst du Cloud und seine Dienste über REST API, OpenAPI und Webhooks integrieren; dies ersetzt nicht die Prüfung der spezifischen Regeln für die jeweilige Ressource.

Führe die Tests abschließend in einer kontrollierten Umgebung aus und lege fest, wie Fehler beobachtet werden: mit Protokollen, die keine geheimen Identifikatoren enthalten, Synchronisierungsstatus und Warnungen für mehrdeutige Zuordnungen. Wiederhole die Prüfung, wenn sich die Spezifikationsversion oder die Synchronisierungslogik ändert. Erfolg bedeutet nicht, dass die Namen übereinstimmen, sondern dass jede externe Referenz zur vorgesehenen Ressource führt oder sichtbar und nachvollziehbar wiederherstellbar fehlschlägt.

• Ist der Identifikator samt Geltungsbereich dokumentiert?
• Wurden Umbenennen, Verschieben, Löschen und Neuerstellen getestet?
• Sind Fehler und mehrdeutige Treffer sichtbar und lässt sich auf sie reagieren?
• Verhindert die Integration, eine Ressource allein wegen eines übereinstimmenden Namens oder Pfads neu zuzuordnen?

Häufige Fragen