Tabellendaten in APIs: Mehrdeutige Formate und Tageswechsel vermeiden

Warum ein gleich aussehendes Datum Verschiedenes bedeuten kann

Eine Zelle kann „03/04/2025“ anzeigen. In einem internationalen Austausch kann das je nach vereinbartem Gebietsschema oder den Regeln der API für den 3. April oder den 4. März stehen. Die Tabelle kann den Wert abhängig von ihren Einstellungen, dem Zellenformat oder der Art der Eingabe interpretieren. Bei der Übermittlung an ein anderes System kann auch die API eigene Regeln anwenden. Microsoft weist darauf hin, dass die Regeln zur Datumsinterpretation in Tabellenkalkulationsprogrammen komplex sein können, und empfiehlt, sie möglichst genau festzulegen – in der [Anleitung zu Datumssystemen, Formaten und Datumsinterpretation](https://support.microsoft.com/es-es/excel/change-the-date-system-format-or-two-digit-year-interpretation).

Verwenden Sie deshalb nicht die visuelle Darstellung als Integrationsvertrag. Ermitteln Sie vor dem Export, welche Zellen Datumsangaben enthalten, welchen Wert sie darstellen und wie das empfangende System diese erhalten soll. Die [Anleitung zu Datums- und Zahlenformaten der Google Sheets API](https://developers.google.com/workspace/sheets/api/guides/formats?hl=es-419) beschreibt Formatmuster, die in Anfragen enthalten sein können. Prüfen Sie in der Dokumentation des jeweiligen Dienstes, welche Formate er unterstützt.

• Vermeiden Sie numerische Datumsangaben, bei denen Tag und Monat vertauscht werden können, wenn der Vertrag ihre Reihenfolge nicht festlegt.
• Gehen Sie nicht davon aus, dass das sichtbare Zellenformat bestimmt, wie die API den Wert interpretiert.

Legen Sie fest, ob das Feld ein Kalenderdatum oder einen Zeitpunkt darstellt

Definieren Sie vor der Wahl eines Formats, was das Feld bedeutet. In diesem Leitfaden bezeichnet ein Kalenderdatum einen Tag, etwa das Fälligkeitsdatum einer Aufgabe; für sich genommen enthält es weder eine Uhrzeit noch einen Ortsbezug. Ein Zeitpunkt bezeichnet einen konkreten Moment, etwa den Zeitpunkt, zu dem ein Vorgang erfasst wurde. Auch wenn beide Werte in einer Tabelle wie Datumsangaben aussehen, muss der Vertrag klären, welche Bedeutung erwartet wird.

Halten Sie diese Unterscheidung im Datenvertrag fest, nicht nur in einer informellen Notiz. Dokumentieren Sie für jede Spalte den Namen, die Bedeutung, den erwarteten Typ, ob leere Werte zulässig sind und ein gültiges Beispiel. Wenn ein Feld nur einen Tag bezeichnet, fügen Sie keine fiktive Uhrzeit hinzu, um eine Integration zufriedenzustellen. Wenn es einen Zeitpunkt darstellt, geben Sie an, wie Uhrzeit und der vom empfangenden System benötigte Zeitzonenbezug ausgedrückt werden.

• Fragen Sie: „Soll der Wert für alle Nutzer derselbe Kalendertag bleiben?“ Wenn ja, definieren Sie das Feld als Kalenderdatum.
• Fragen Sie: „Müssen wir wissen, wann etwas geschehen ist?“ Wenn ja, legen Sie den Umgang mit Uhrzeit und Zeitzonenbezug für diese Integration fest.

Verwenden Sie eine eindeutige Darstellung und einen Datenvertrag

Als Format für den Vertrag dieser Integration können Sie ein geordnetes Muster für Jahr, Monat und Tag wie „2025-04-03“ statt „03/04/2025“ wählen. Legen Sie für Zeitpunkte auch fest, wie Uhrzeit und Zeitzonenbezug ausgedrückt werden. Verlassen Sie sich nicht auf die regionalen Einstellungen einer Tabelle: Erzeuger und Empfänger müssen dasselbe Format und dieselbe Bedeutung vereinbaren.

Dokumentieren Sie relevante Ausnahmen für den jeweiligen Dienst: ob Sekunden zulässig sind, welche Genauigkeit gilt, wie der Zeitzonenbezug angegeben wird und was als ungültig gilt. Verwechseln Sie Format und Bedeutung nicht: Eine Zelle, die als Datum angezeigt wird, könnte Text oder einen anderen Wert enthalten. Die oben genannte Anleitung zur Google Sheets API behandelt Formatmuster, die in Anfragen enthalten sein können. Sie ersetzt weder die Definition des Vertrags noch legt sie eigenständig fest, was ein Feld in Ihrer Integration bedeutet.

• Legen Sie für jede Spalte Format, Typ, gegebenenfalls Zeitzonenbezug, Genauigkeit, Pflichtangabe und ein Beispiel fest.
• Weisen Sie Werte zurück, die den Vertrag nicht erfüllen, oder leiten Sie sie zur Prüfung weiter. „Korrigieren“ Sie sie nicht stillschweigend.

Legen Sie den Zeitzonenbezug fest, wenn der Wert ihn benötigt

Wenn das Feld nur ein Kalenderdatum ausdrückt, legen Sie fest, ob der Prozess zusätzliche Zeitangaben benötigt. Vereinbaren Sie bei einem Ereignis mit konkreter Uhrzeit den Zeitzonenbezug, den Erzeuger und Empfänger verwenden, und dokumentieren Sie die Entscheidung im Vertrag. Vermeiden Sie, eine Ortszeit an einer Stelle des Ablaufs mit einer abweichenden Interpretation an anderer Stelle zu vermischen.

Wenn der Ablauf die Ortszeit eines Ereignisses erhalten muss, dokumentieren Sie die Vorgehensweise und testen Sie die für diese Integration wichtigen Fälle, auch solche nahe Mitternacht. Ein beim Anzeigen festgestellter Tageswechsel reicht für sich genommen nicht aus, um auf eine Beschädigung des ursprünglichen Werts zu schließen: Vergleichen Sie das Ergebnis mit der im Vertrag festgelegten Bedeutung und den dort beschriebenen Regeln. Wenn das Feld nur ein Kalenderdatum ausdrückt, vermeiden Sie Zeitangaben, die der Prozess nicht benötigt.

• Dokumentieren Sie für jeden Zeitpunkt den zwischen Erzeuger und Empfänger vereinbarten Zeitzonenbezug.
• Prüfen Sie für Ihren Ablauf relevante Fälle nahe Mitternacht. Bevor Sie einen Fehler feststellen, vergleichen Sie das Ergebnis mit dem Vertrag.

Testen Sie die für Ihre Integration festgelegten Fälle

Erstellen Sie zum Prüfen eines konkreten Ablaufs Testfälle, die zum Vertrag passen. Dazu können Datumsangaben gehören, bei denen Tag und Monat verwechselt werden könnten, Werte nahe einem Tageswechsel, eine leere Zelle, Text, der kein Datum ist, sowie ein Wert mit unerwarteter Genauigkeit oder unerwartetem Zeitzonenbezug. Legen Sie vorab fest, ob jeder Fall angenommen, zurückgewiesen oder zur Prüfung zurückgestellt werden soll. Diese Liste ist eine Validierungspraxis für die Integration und keine Aussage über Anforderungen einer externen Norm.

Für leere Werte sollte eine eigene Regel gelten. Definieren Sie, was eine leere Zelle bedeutet, und verhindern Sie, dass der Prozess ihr automatisch einen anderen, nicht vereinbarten Wert zuweist. Wenn der Ablauf zwischen „keine Angabe“, „unbekannt“ und „nicht zutreffend“ unterscheiden muss, dokumentieren Sie diese Möglichkeiten. Legen Sie für ungültige Werte eine erkennbare Reaktion fest oder halten Sie die Übermittlung an, damit die Quelle korrigiert werden kann. Ersetzen Sie Werte nicht stillschweigend.

• Mögliche Testfälle: mehrdeutiges Datum, Monatsende, Jahreswechsel, Mitternacht, leerer Wert und ungültiger Text.
• Prüfen Sie, was der Empfänger erhält und was der Betreiber bei einer fehlgeschlagenen Validierung sieht.

Prüfen Sie den gesamten Datenweg, bevor Sie ihn nutzen

Erstellen Sie als praktische Prüfung des konkreten Ablaufs einen kleinen Satz repräsentativer Datensätze und bewahren Sie eine Kopie ihrer ursprünglichen Werte auf. Senden Sie sie durch den vorgesehenen Ablauf und prüfen Sie den empfangenen Wert. Wenn der Prozess das erneute Laden in eine Tabelle umfasst, kontrollieren Sie auch das Ergebnis dort. Vergleichen Sie die Bedeutung, nicht nur das Erscheinungsbild: Ein Datum, das mit einem anderen visuellen Stil zurückkommt, kann weiterhin korrekt sein, während ein Tages- oder Uhrzeitwechsel gegen den Vertrag verstoßen kann.

Wiederholen Sie die Prüfung mit den ausgewählten Fällen und notieren Sie das erwartete und das beobachtete Ergebnis. Wenn eine Abweichung auftritt, prüfen Sie, an welcher Stelle sie entsteht: bei der Interpretation durch die Tabelle, bei der Umwandlung, in der API-Anfrage oder bei der Darstellung der Antwort. Passen Sie den Vertrag oder die Konvertierung an und führen Sie denselben Testsatz erneut aus, um das Ergebnis der Änderung zu überprüfen.

• Speichern Sie Eingabe, gesendeten Wert, Antwort und sichtbares Ergebnis, damit Sie jeden Schritt vergleichen können.
• Betrachten Sie die Prüfung nur dann als bestanden, wenn die vereinbarte Bedeutung erhalten bleibt und die vorgesehenen Fehler erkannt werden.

Prüfung und Integration in Apification organisieren

Halten Sie als Arbeitsweise eine Testtabelle getrennt von den operativen Daten. In Apification Cloud können Sie Dateien und Projekte in einem versionierten Arbeitsbereich organisieren und Tabellen mit ONLYOFFICE erstellen oder bearbeiten, ohne sie aus dem Cloud-Speicher zu verschieben. Prüfen Sie dort vor der Vorbereitung der Integration Überschriften, sichtbare Formate, leere Zellen und Beispiele. Die Tabelle erleichtert dem Team die Sichtprüfung, ersetzt jedoch nicht die Validierungsregeln des Dienstes, der die Daten empfängt oder sendet.

Apification ermöglicht die Integration von Cloud und seinen Diensten über REST API, OpenAPI, Webhooks, iframe und JavaScript. Ziehen Sie die einschlägige API-Dokumentation heran, um den tatsächlichen Austausch festzulegen. Leiten Sie aus diesen Möglichkeiten keine bestimmten Endpunkte oder Verhaltensweisen ab. Nach einer wichtigen Änderung können Sie im Elementverlauf von Cloud frühere Versionen prüfen, herunterladen und Inhalte wiederherstellen. Das hilft, eine Arbeitsdatei wiederherzustellen, ersetzt jedoch weder die Prüfung des Vertrags noch die Kontrolle der Ergebnisse.

• Validieren Sie vor der Verbindung echter Daten eine Arbeitskopie mit repräsentativen Beispielen und vereinbarten Regeln.
• Prüfen Sie in der API-Dokumentation, welche Operation und welches Format der jeweilige Dienst unterstützt.
• Prüfen Sie nach einer Änderung an einer Tabelle ihren Versionsverlauf und behalten Sie eine bekannte Version zur einfacheren Wiederherstellung.

Häufige Fragen