Compatibilidad con proyectos públicos Azure DevOps Services extensiones

  • Artículo
  • Tiempo de lectura: 8 minutos

Azure DevOps Services

Antes de la compatibilidad con proyectos públicos, todos Azure DevOps Services proyectos eran privados. Los proyectos privados solo autenticaban a los usuarios con acceso al proyecto, por lo que el público no podía verlo ni interactuar con él. Un proyecto público permite a los usuarios que no son miembros ver el contenido de ese proyecto en un estado de solo lectura.

Un usuario que no es miembro es anónimo (no autenticado en Azure DevOps Services) o público (se autentica en Azure DevOps Services, pero no pertenece a la organización).

Los usuarios que no son miembros suelen ver las mismas vistas que los usuarios autenticados, pero la funcionalidad no pública está oculta o deshabilitada. Un ejemplo de funcionalidad no pública, como la configuración y las acciones, incluye una compilación de cola.

Nota

Azure DevOps Services compatibilidad con proyectos públicos se encuentra actualmente en versión preliminar limitada. Póngase en vsts-public@microsoft.com contacto con si está interesado en desarrollar extensiones que admitan proyectos públicos. Para más información sobre los proyectos públicos, consulte Azure DevOps Services Versión preliminar limitada de proyectos públicos.

Decidir si hacer que una extensión sea visible para los usuarios que no son miembros

Como desarrollador de extensiones, puede hacer que todo o parte de la extensión esté disponible para los usuarios que no son miembros. Estos usuarios solo pueden usar la extensión desde dentro de un proyecto público. Si decide no hacer que la extensión esté disponible para los usuarios que no son miembros, no se requiere ningún cambio y no hay ningún impacto en los miembros, ya sea que usen la extensión desde un proyecto público.

Use esta lista de comprobación para decidir si debe hacer que la extensión esté disponible para usuarios que no son miembros:

  • Los datos presentados por la extensión son pertinentes para los usuarios que no son miembros
  • La extensión aporta funcionalidades en el nivel de proyecto
  • La extensión contribuye a las áreas del producto a las que pueden acceder usuarios que no son miembros
  • La extensión no extiende ni se basa en características que no están disponibles para los usuarios que no son miembros, por ejemplo, el servicio de datos o determinadas AZURE DEVOPS SERVICES REST. Para más información, consulte la sección Limitaciones de este artículo.

Visibilidad de la contribución

De forma predeterminada, las contribuciones solo son visibles para los miembros de la organización. Para proporcionar visibilidad a los usuarios que no son miembros de una contribución, establezca el restrictedTo atributo en esa contribución. El valor es una matriz de cadenas que enumera los tipos de usuarios que deben tener visibilidad de la contribución. Los valores posibles son:

  • member un usuario autenticado que sea miembro de la organización
  • public un usuario autenticado que no es miembro de la organización
  • anonymous un usuario no autenticado

Ejemplo: hacer que un centro sea visible para usuarios anónimos, públicos y miembros

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

También puede establecer la visibilidad predeterminada de todas las contribuciones de la extensión estableciendo restrictedTo el atributo en la raíz del manifiesto de extensión. A continuación, puede invalidar este valor predeterminado en contribuciones individuales.

Ejemplo: hacer que todas las contribuciones, excepto una, sean visibles para todos los usuarios

{
    "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": {  
                ...              
            }
        }            
    ]
}

Limitaciones

Si desea que algunos o todos los aspectos de su contribución estén disponibles para los usuarios públicos, tenga en cuenta las siguientes limitaciones.

Métodos del SDK de VSS

El script del SDK principal, VSS.SDK.js, permite que las extensiones web se comuniquen con el marco primario para realizar operaciones como inicializar la comunicación y obtener información de contexto sobre el usuario actual. Los siguientes métodos del SDK de VSS no se admiten para usuarios que no son miembros:

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

Servicio de datos de extensión

Dado que los datos administrados por el servicio de datos de extensión no están limitados ni protegidos para un proyecto, los usuarios que no son miembros no pueden leer ni escribir ningún tipo de datos de extensión.

Ejemplo: control de errores de acceso a datos

Si el servicio de datos no puede acceder al servicio de datos debido a las limitaciones de permisos del usuario que realiza la llamada, getValue se rechaza la promesa devuelta por la llamada a . El error pasado a la función reject tiene un nombre, que puede ayudarle a comprender por qué la llamada no pudo leer o escribir datos.

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

API de REST

Hay un conjunto limitado de Azure DevOps Services API REST disponibles para usuarios que no son miembros. Estas API incluyen la mayoría de las API de nivel de organización y de nivel de proyecto para las características que no están disponibles para los usuarios que no son miembros en general. Tenga en cuenta esta información cuando decida si quiere que la extensión esté disponible para los usuarios que no son miembros.

Se recomienda usar las API de la versión 5.0 y posteriores, ya que determinadas API solo están disponibles para usuarios que no son miembros a partir de la versión 5.0.

Referencias de identidad

La mayoría de Azure DevOps Services API REST usan un "contrato" común para representar a un usuario o grupo. Para proteger la información de los miembros, como las direcciones de correo electrónico, cuando un usuario anónimo o público invoca una API REST, se omiten determinados campos, uniqueName como .

Comprobación de permisos de usuario

Use permisos para decidir si se va a abrir o habilitar una funcionalidad en la extensión. La API REST de seguridad se usa desde el código de extensión web para comprobar si el usuario actual tiene permiso en Azure DevOps Services para completar la tarea. De este modo, el usuario no pensará que tiene permiso para hacer algo, solo para averiguar que no lo hace.

Ejemplo: comprobar si el usuario tiene permiso para poner en cola las compilaciones

En este ejemplo se muestra cómo usar el cliente REST de seguridad para comprobar si el usuario tiene permisos para poner en cola las compilaciones en el proyecto actual. De forma predeterminada, los usuarios que no son miembros no tienen este permiso.

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);
  });
});

Consideraciones sobre el widget de panel

Al igual que otros tipos de contribuciones, la visibilidad de las contribuciones del widget de panel se controla con la propiedad restrictedTo de contribución. Por ejemplo, para que un widget sea visible para usuarios que no son miembros y miembros:

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

Configuración del widget

Al controlar la visibilidad del widget para los usuarios que no son miembros, el marco de trabajo del panel también proporciona un mecanismo de almacenamiento opcional de forma abierta para la configuración del widget. Hay dos mecanismos disponibles para indicar si la configuración del widget está disponible para su uso por parte de usuarios que no son miembros en proyectos públicos.

Un widget con una configuración configurable que sea visible para los usuarios que no son miembros debe seguir uno de los siguientes patrones. Si no lo hace, el widget no se muestra a estos usuarios.

Patrón 1: el widget declara sus instancias solo para almacenar la configuración específica del proyecto

Establezca la propiedad de la contribución del canStoreCrossProjectSettings widget en false, lo que indica que la configuración del widget es específica del proyecto.

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

Patrón 2: una instancia de widget declara que su configuración es específica del proyecto.

Las instancias de widget individuales también pueden indicar que su configuración es específica del proyecto y está disponible para los usuarios que no son miembros. Al guardar la configuración, el widget debe establecer en hasCrossProjectSettings en false la cadena JSON con cadena:

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

Consideraciones de compilación y versión

Si la extensión contribuye a una tarea de compilación o versión, no se requiere ningún cambio para usar esa tarea desde una canalización en un proyecto público.

Consideraciones sobre el seguimiento de elementos de trabajo

Las extensiones no funcionan para usuarios que no son miembros en el contexto de un proyecto público sin cambios. Esto incluye el formulario de elemento de trabajo, otras experiencias de elementos de trabajo o la interacción con las API REST de seguimiento de elementos de trabajo.

Formulario de elemento de trabajo

Se producirá un error en todas las actualizaciones o eliminaciones de elementos de trabajo para usuarios que no son miembros.

Identities

En Azure DevOps Services api REST versión 5.0 y posteriores, las identidades IdentityRef se devuelven como objetos en lugar de cadenas. Como se ha descrito anteriormente, determinados campos, uniqueName como , no se devuelven en estos objetos si un usuario que no es miembro realizó la llamada API.

API existentes

Solo las API REST con ámbito de proyecto se pueden invocar mediante una extensión cuando el usuario actual no es miembro de la organización. Se rechazan todas las llamadas API REST que no estén en el ámbito de un proyecto.

Consultas

Existen las siguientes limitaciones para los usuarios que no son miembros relacionados con las consultas de elementos de trabajo:

  • Los usuarios que no son miembros pueden ejecutar consultas conocidas por identificador o ruta de acceso
  • Las consultas deben tener como ámbito el proyecto actual. Se excluyen todos los elementos de trabajo que no pertenezcan al proyecto actual.
  • El usuario que no es miembro no puede crear nuevas consultas ni ejecutar consultas WIQL