Aktualisierungen und Versionierungen
Benutzerdefinierte Konnektoren, die durch Zertifizierung veröffentlicht oder als Open Source erstellt wurden, können weiterhin aktualisiert werden. Der Vorgang zum Ausführen des Updates ist nahezu identisch mit der Erstveröffentlichung. Der Hauptunterschied besteht darin, dass Sie Ihre vorhandenen Benutzer bei der Planung Ihrer Updates berücksichtigen müssen. Grundlegende Änderungen an Ihrer Konnektordefinition, auch wenn diese geringfügig sind, können sich auf vorhandene Benutzer auswirken.
Die Trigger und Aktionen eines Konnektors können im Laufe der Zeit zunehmen und sich ändern, wenn Features in der zugrunde liegenden API hinzugefügt oder erweitert werden. Einige Änderungen bedeuten lediglich Zusätze und gefährden nicht die bestehende Basis zwischen Apps und Flows, die Ihren Konnektor verwenden. Das Hinzufügen neuer Parameter, das Zurückgeben weiterer Daten oder das Zulassen flexiblerer Eingaben kann in diese Kategorie fallen. Viele Änderungen können jedoch die Basis gefährden, die in der OpenAPI-Spezifikation beschrieben ist.
Beispiele für grundlegende Änderungen sind:
Entfernen von Parametern
Bestimmte Eingaben werden nicht mehr unterstützt
Ändern der Bedeutung und des Verhaltens einer Eingabe, Ausgabe oder Operation
Die API, die Ihr benutzerdefinierter Konnektor beschreibt, muss diese grundlegenden Änderungen ebenfalls vermeiden. In Fällen, in denen verschiedene Gruppen die Konnektordefinition und die API beibehalten, muss eine Koordination erfolgen, um sie synchron zu halten.
Stellen Sie sicher, dass Sie einem Muster folgen, das von den Benutzern des Konnektors erkannt werden kann, um einen benutzerdefinierten Konnektor und eine API sicher weiterzuentwickeln. Es liegt in der Verantwortung des Konnektors und damit auch der API, die Abwärtskompatibilität aufrechtzuerhalten, die Absicht zu kommunizieren und die Versionsattribute abzugrenzen. Es liegt in der Verantwortung des Tooldesigners, die Verwendung des Konnektors zum Ein- oder Ausblenden von Vorgängen zuzulassen, die veraltet oder abgelaufen sind oder für die möglicherweise neuere Versionen verfügbar sind. Auf diese Weise können Vorgänge im Laufe der Zeit wachsen und sich entwickeln, ohne dass Anwendungen, die auf ihnen basieren, übermäßig anfällig werden.
Konnektoraktionen kommentieren
Mithilfe der OpenAPI-Konfiguration können Sie die Aktionen in Ihrem Konnektor kommentieren, sodass sie, wenn sie in der Entwurfsoberfläche angezeigt werden, die beabsichtigte Verwendung vermitteln. Beispielsweise haben Sie durch das Hinzufügen der OpenAPI-Erweiterung x-ms-api-annotation zur Aktion GetInvoice angegeben, dass der Status eine Vorschau ist.
Wenn diese Aktion im Power Automate-Cloud-Flow-Designer angezeigt wird, wird sie daher (als Vorschau) nach dem Aktionsnamen angezeigt.
Neue Versionen einer Aktion
Ab einem gewissen Punkt in der Lebensdauer der Aktion stellen Sie möglicherweise fest, dass Sie eine grundlegende Änderung einführen müssen. Am besten erstellen Sie eine neue Version der Aktion. Bestehende Benutzer der ursprünglichen Aktion sind nicht betroffen, aber neue Benutzer können die neue Version nutzen. Es ist üblich, die Version als Teil der Zusammenfassung anzugeben. Der folgende Screenshot zeigt, wie dieser Prozess aussehen würde.
Eine Aktion einstellen
Nachdem Sie Ihre neue Aktion eingeführt haben, möchten Sie möglicherweise die alte Aktion einstellen, damit sie nicht mehr in neuen Apps und Flows verwendet wird. Ein guter erster Schritt wäre, die alte Aktion im Abschnitt Sichtbarkeit als Erweitert zu markieren. Wenn Sie Aktionen haben, die als Wichtig gekennzeichnet sind, sollten Sie überlegen, ob die neue V2-Aktion auch als Wichtig markiert werden soll. Beide Änderungen der Sichtbarkeit fördern die Verwendung der neuen Aktion, indem sie in der Liste der Aktionen höher platziert wird.
Sie können in der Zusammenfassung oder Beschreibung auch einen Hinweis auf ein bevorstehendes Einstellen angeben. Sie könnten beispielsweise Rechnung abrufen in Rechnung abrufen (eingestellt) ändern. Diese Auswahl kann das Einstellen langsam ankündigen, ohne sie vor den Benutzern zu verbergen. Ziel ist es, die Benutzer des Konnektors durch die von Ihnen vorgenommenen Änderungen zu navigieren.
Um die Aktion vor neuen Benutzern auszublenden, vorhandene Benutzer jedoch nicht auszuschließen, können Sie die Aktion als Veraltet in der OpenAPI-Konfiguration markieren. Sie können diese Änderung vornehmen, indem Sie die OpenAPI-Definition direkt mit dem Swagger-Editor bearbeiten. Fügen Sie der Operationskonfiguration den folgenden Befehl hinzu, um anzuzeigen, dass eine Aktion veraltet ist:
deprecated: true
Nachdem der Konnektor veröffentlicht wurde, blendet dieser Befehl die Aktion aus, damit der Benutzer sie nicht in neuen Flows auswählen kann.
Es gibt viele Gründe, sich an die Versionierung von Aktionen zu halten. In erster Linie wird dadurch sichergestellt, dass Clients wie Logic Apps und Power Automate weiterhin ordnungsgemäß funktionieren, wenn Benutzer Konnektoraktionen in ihre Flows integrieren. Aktionen sollten mithilfe der oben genannten Methoden versioniert werden, wenn eine der folgenden Bedingungen erfüllt ist:
Eine neue Revision einer Aktion wird hinzugefügt.
Eine vorhandene Aktion fügt Parameter hinzu oder entfernt sie.
Eine vorhandene Operation ändert die Eingabe oder Ausgabe erheblich.
In einigen Situationen kann es vorkommen, dass Sie die Versionierung vermeiden können. Sie sollten jedoch vorsichtig sein und zahlreiche Tests durchführen, um sicherzustellen, dass Sie Grenzfälle nicht übersehen haben, in denen die Apps und Flows der Benutzer möglicherweise unerwartet beschädigt werden.
Sie können (vorsichtig) die Versionierung vermeiden, wenn:
Eine neue Aktion wird hinzugefügt.
Ein neuer optionaler Parameter zu einer vorhandenen Aktion hinzugefügt wird.
Eine vorhandene Aktion das Verhalten auf subtile Weise ändert.
Wir empfehlen, dass Sie auf Nummer sicher gehen und eine Revision erstellen, wenn Sie grundlegende Änderungen an einer Konnektordefinition oder der zugrunde liegenden API vornehmen.