Entwickeln von Erweiterungen für öffentliche Projekte

Azure DevOps Services

Azure DevOps Services unterstützt sowohl private als auch öffentliche Projekte. Private Projekte beschränken den Zugriff auf authentifizierte Benutzer mit expliziten Berechtigungen. Öffentliche Projekte erlauben es Nichtmitgliedern, Projektinhalte in einem schreibgeschützten Zustand zu betrachten.

Ein Nichtmitglied kann entweder Folgendes sein:

• Anonym: Nicht authentifiziert bei Azure DevOps Services
• Öffentlich: Authentifiziert bei Azure DevOps Services, aber nicht mitglied der Organisation

Nicht-Mitgliedsbenutzer sehen die gleichen Ansichten wie authentifizierte Benutzer, aber Azure DevOps blendet nichtöffentliche Funktionen wie Einstellungen, Aktionen und Build-Warteschlangen-Vorgänge aus oder deaktiviert sie.

Sichtbarkeit der Erweiterung für Nichtmitglieder

Als Erweiterungsentwickler können Sie alle oder einen Teil Ihrer Erweiterung für Nichtbenutzer verfügbar machen. Diese Benutzer können Ihre Erweiterung nur in öffentlichen Projekten verwenden. Wenn Sie Ihre Erweiterung nicht für Nichtbenutzer verfügbar machen möchten, benötigen Sie keine Änderungen, und die Entscheidung hat keine Auswirkungen auf Mitglieder, die Ihre Erweiterung in öffentlichen Projekten verwenden.

Verwenden Sie diese Checkliste, um zu entscheiden, ob Ihre Erweiterung für Nichtbenutzer verfügbar sein soll:

Konfigurieren der Sichtbarkeit von Beiträgen

Standardmäßig zeigt Azure DevOps nur Beiträge für Organisationsmitglieder an. Um Nichtmitgliedern eine Sichtbarkeit für einen Beitrag zu ermöglichen, legen Sie das restrictedTo-Attribut für diesen Beitrag fest. Der Wert ist ein Zeichenfolgenarray, das auflistet, welche Benutzertypen den Beitrag sehen sollen. Zu den möglichen Werten gehören:

• member: Ein authentifizierter Benutzer, der Mitglied der Organisation ist
• public: Ein authentifizierter Benutzer, der kein Mitglied der Organisation ist
• anonymous: Ein nicht authentifizierter Benutzer

Hub für alle Benutzer sichtbar

{
    "contributions": [
        {
            "id": "my-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                "ms.vss-code-web.code-hub-group"
            ],
            "restrictedTo": [
                "member",
                "public",
                "anonymous"
            ],
            "properties": {
                ...            
            }
        }
    ]
}

Sie können auch die Standardsichtbarkeit für alle Beiträge in Ihrer Erweiterung festlegen, indem Sie das restrictedTo Attribut im Stammverzeichnis Ihres Erweiterungsmanifests festlegen. Sie können diese Standardeinstellung dann für einzelne Beiträge außer Kraft setzen.

Sichtbar für alle außer einem Beitrag

{
    "id:": "my-extension",
    "name": "My Extension",
    "version": "1.0.0",
    ...
    "restrictedTo": [
           "anonymous",
           "public",
           "member"
    ],
    "contributions": [
        {
            "id": "my-member-only-widget",
            "type": "ms.vss-dashboards-web.widget",
            "restrictedTo": [
                "member"
            ],
            "properties": {
                ...
            }
        },
        {
            "id": "my-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                "ms.vss-code-web.code-hub-group"
            ],
            "properties": {  
                ...              
            }
        },
        {
            "id": "my-second-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                "ms.vss-work-web.work-hub-group"
            ],
            "properties": {  
                ...              
            }
        }            
    ]
}

Einschränkungen für Nichtmitglieder

Wenn Sie einige oder alle Aspekte Ihres Beitrags für öffentliche Benutzer zur Verfügung stellen möchten, sollten Sie die folgenden Einschränkungen berücksichtigen.

VSS SDK-Methodeneinschränkungen

Das kerne SDK-Skript, VSS.SDK.js, ermöglicht es Weberweiterungen, mit dem übergeordneten Frame zu kommunizieren, um Vorgänge wie initialisieren der Kommunikation und Abrufen aktueller Benutzerkontextinformationen auszuführen. Die folgenden VSS SDK-Methoden unterstützen Nichtmitglieder nicht:

• VSS.getAccessToken()
• VSS.getAppToken()

Einschränkungen des Erweiterungsdatendiensts

Da der Erweiterungsdatendienst Daten verwaltet, die nicht auf ein Projekt festgelegt oder gesichert sind, können Nichtbenutzer keine Erweiterungsdaten lesen oder schreiben.

Behandeln von Datenzugriffsfehlern

Wenn der Datendienst aufgrund von Berechtigungseinschränkungen durch den aufrufenden Benutzer nicht auf Daten zugreifen kann, wird die vom Aufruf getValue zurückgegebene Zusage abgelehnt. Der an die Reject-Funktion übergebene Fehler verfügt über eine Namenseigenschaft, die Ihnen hilft, zu verstehen, warum der Aufruf keine Daten lesen oder schreiben konnte.

VSS.getService(VSS.ServiceIds.ExtensionData).then(function(dataService) {
    dataService.getValue("someKey").then(function(value) {
         // Process the value
    }, function(error) {
       if (error.name === "AccessCheckException") {
           alert(error.message);
       }
    });
});

REST-API-Zugriff

Azure DevOps Services bietet einen begrenzten Satz von REST-APIs für Nichtbenutzer. Diese APIs umfassen die meisten APIs auf Organisations- und Projektebene für Funktionen, auf die Nichtmitglieder im Allgemeinen zugreifen können. Berücksichtigen Sie diese Informationen, wenn Sie entscheiden, ob Ihre Erweiterung für Nichtbenutzer verfügbar sein soll.

Verwenden Sie Version 5.0 und höhere APIs, da Azure DevOps bestimmte APIs nur für Nichtbenutzer verfügbar macht, die mit Version 5.0 beginnen.

Identitätsreferenzen

Die meisten Rest-APIs von Azure DevOps Services verwenden einen allgemeinen "Vertrag", um einen Benutzer oder eine Gruppe darzustellen. Um Mitgliedsinformationen wie E-Mail-Adressen zu schützen, lässt Azure DevOps bestimmte Felder, wie uniqueName, aus, wenn es von einem anonymen oder öffentlichen Benutzer eine REST-API aufgerufen wird.

Überprüfen Sie die Benutzerberechtigungen.

Verwenden Sie Berechtigungen, um zu entscheiden, ob eine Funktion in Ihrer Erweiterung angezeigt oder aktiviert werden soll. Verwenden Sie die Sicherheits-REST-API aus Weberweiterungscode, um zu überprüfen, ob der aktuelle Benutzer über die Berechtigung in Azure DevOps Services verfügt, um die Aufgabe abzuschließen. Dieser Ansatz verhindert, dass Benutzer denken, dass sie berechtigt sind, etwas zu tun, nur um zu ermitteln, dass sie nicht.

Überprüfen der Berechtigungen für die Build-Warteschlange

In diesem Beispiel wird gezeigt, wie Sie mithilfe des Security REST-Clients überprüfen können, ob der Benutzer über die Berechtigungen verfügt, um Builds in die Warteschlange zu stellen im aktuellen Projekt. Standardmäßig besitzen Nichtbenutzer diese Berechtigung nicht.

VSS.require(["VSS/Service", "VSS/security/RestClient"], function(VSS_Service, Security_RestClient) {
   var client = VSS_Service.getCollectionClient(Security_RestClient.SecurityHttpClient3);
 
   var securityToken = VSS.getWebContext().project.id;
 
   client.hasPermissionsBatch({
    evaluations: [
       {
           "securityNamespaceId": "33344D9C-FC72-4d6f-ABA5-FA317101A7E9",
           "token": securityToken,
           "permissions": 128 /* queue builds */
       }
    ],
    alwaysAllowAdministrators: true
}
).then(function(response) {
     console.log("Can user queue builds in this project? " + response.evaluations[0].value);
  });
});

Dashboard-Widgetanforderungen

Genau wie andere Arten von Beiträgen steuert die restrictedTo Beitragseigenschaft die Sichtbarkeit von Dashboard-Widget-Beiträgen. Um beispielsweise ein Widget für Nichtbenutzer und Mitgliedsbenutzer sichtbar zu machen:

{
  "contributions": [
    {
      "id": "HelloWorldWidget",
      "type": "ms.vss-dashboards-web.widget",
      "targets": [
        "ms.vss-dashboards-web.widget-catalog"
      ],
      "restrictedTo": [
        "member",
        "public",
        "anonymous"
      ],
      "properties": {
          ...
      }
    }
  ]
}

Konfigurieren von Widgeteinstellungen

Wenn Sie die Sichtbarkeit von Widgets für Nichtmitglieder steuern, bietet das Dashboard-Framework auch einen optionalen, Open-Form Storage-Mechanismus für Widget-Einstellungen. Zwei Mechanismen geben an, ob Widgeteinstellungen für Nichtbenutzer in öffentlichen Projekten verfügbar sind.

Ein Widget mit konfigurierbaren Einstellungen, das für Nichtbenutzer sichtbar ist, muss einem der folgenden Muster folgen. Wenn Sie diese Muster nicht befolgen, wird verhindert, dass das Widget für diese Benutzer angezeigt wird.

Projektspezifische Einstellungen (Erweiterungsebene)

Setzen Sie die Eigenschaft canStoreCrossProjectSettings des Widget-Beitrags auf false, um anzuzeigen, dass die Widget-Einstellungen projektspezifisch sind.

{
    "id:": "HelloWorldWidget",
    "type": "ms.vss-dashboards-web.widget",
    ...
    "properties": {
        "canStoreCrossProjectSettings": false
    }
}

Projektspezifische Einstellungen (Instanzebene)

Einzelne Widgetinstanzen können auch angeben, dass ihre Einstellungen projektspezifisch und für Nichtbenutzer verfügbar sind. Wenn Sie die Einstellungen speichern, sollte das Widget in der JSON-Zeichenfolge hasCrossProjectSettings auf false festlegen:

{
    "hasCrossProjectSettings": false,
    "hypotheticalWidgetOption": true,
    "backlogLevel": "Stories"
}

Build- und Releaseanforderungen

Wenn Ihre Erweiterung einen Build- oder Freigabevorgang beiträgt, benötigen Sie keine Änderungen, um diesen Vorgang aus einer Pipeline in einem öffentlichen Projekt zu verwenden.

Überlegungen zur Nachverfolgung von Arbeitsaufgaben

Erweiterungen funktionieren für Nichtmitglieder im Kontext eines öffentlichen Projekts nicht ohne Änderungen, einschließlich des Arbeitselement-Formulars, anderer Arbeitselement-Erfahrungen und der Interaktion mit REST-APIs zur Verfolgung von Arbeitselementen.

Einschränkungen des Arbeitselement-Formulars

Azure DevOps lehnt alle Aktualisierungen von Arbeitsaufgaben ab oder löscht sie für Nichtbenutzer.

Identitätsverarbeitung

In Azure DevOps Services REST API Version 5.0 und höher gibt der Dienst Identitäten als IdentityRef Objekte anstelle von Zeichenfolgen zurück. Wie zuvor beschrieben gibt Azure DevOps in diesen Objekten keine bestimmten Felder, wie uniqueName, zurück, wenn ein Nichtmitgliedsbenutzer den API-Aufruf tätigt.

API-Bereichseinschränkungen

Erweiterungen können nur projektbezogene REST-APIs aufrufen, wenn der aktuelle Benutzer kein Organisationsmitglied ist. Azure DevOps lehnt alle REST-API-Aufrufe ab, die nicht den Projektumfang haben.

Abfrageeinschränkungen

Nicht-Mitglieder-Benutzer haben die folgenden Einschränkungen im Zusammenhang mit Abfragen zu Arbeitselementen:

• Nicht-Benutzer können bekannte Abfragen nur anhand der ID oder des Pfads ausführen.
• Abfragen müssen auf das aktuelle Projekt eingeschränkt werden. Azure DevOps schließt alle Arbeitsaufgaben aus, die nicht zum aktuellen Projekt gehören.
• Nichtmitglieder können keine neuen Abfragen erstellen oder WIQL-Abfragen ausführen.

Verwandte Inhalte

• Erweiterungsdatenspeicher
• Rest-API-Referenz für Azure DevOps Services
• Übersicht über öffentliche Projekte
• Erweiterungsmanifestreferenz