Criar um ponto de extremidade de serviço

  • Artigo

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

Os pontos de extremidade de serviço são uma maneira de o Azure DevOps se conectar a sistemas ou serviços externos. Eles são um pacote de propriedades armazenadas com segurança pelo Azure DevOps, que inclui, mas não está limitado às seguintes propriedades:

  • Nome do serviço
  • Description
  • URL do servidor
  • Certificados ou fichas
  • Nomes de utilizador e palavras-passe

As extensões são então capazes de usar o ponto de extremidade do serviço para adquirir os detalhes armazenados para fazer as operações necessárias nesse serviço. Siga este guia para criar uma nova contribuição de ponto de extremidade de serviço e usá-la em sua extensão.

Gorjeta

Confira nossa documentação mais recente sobre desenvolvimento de extensões usando o SDK de Extensão do Azure DevOps.

Visão geral da tarefa

Você pode desenvolver um ponto de extremidade de serviço criando uma extensão de exemplo para o Azure DevOps que inclui os seguintes itens:

  • Um ponto de extremidade de serviço personalizado com fontes de dados, que permite que uma tarefa de compilação ou widget de painel chame um ponto de extremidade REST no serviço/servidor definido pelo ponto de extremidade.
  • Uma tarefa de compilação, que define duas propriedades: O ponto de extremidade de serviço & uma lista de opções, que tem valores preenchidos a partir da fonte de dados do ponto de extremidade REST.

Nota

Quando você cria um ponto de extremidade de serviço, ele está no nível do projeto, não no nível da organização.

As etapas envolvidas na conclusão desta tarefa são:

Nota

Este tutorial refere-se ao diretório inicial do seu projeto como "home".

Crie o arquivo de manifesto: vss-extension.json

O arquivo de manifesto define o ponto de extremidade personalizado e links para o manifesto task.json para a tarefa de compilação.

Neste artigo, a criação do arquivo de manifesto é separada nas três partes a seguir:

Criar arquivo de manifesto básico

Crie um arquivo json (vss-extension.json, por exemplo) no home diretório da sua extensão.

{
"manifestVersion": 1,
  "id": "service-endpoint-tutorial",
  "version": "0.1.1",
  "name": "Sample extension that leverages a service endpoint",
  "description": "A sample Azure DevOps extension which shows how to create a custom endpoint and dynamic build task parameters taking value from a REST API.",
  "publisher": "francistotten",
  "targets": [
    {
      "id": "Microsoft.VisualStudio.Services"
    }
  ],  
  "files": [
    {
      "path": "BuildTaskFolder"
    }
  ]
}

Nota

Atualize a publisher propriedade. O BuildTaskFolder é o caminho onde eventualmente colocaremos nosso pipeline de tarefas de construção.

Adicionar a contribuição de ponto de extremidade personalizada

Adicione a seguinte contributions matriz abaixo da targets matriz do conteúdo do manifesto básico.

Importante

Os parâmetros de conexão de serviço devem ser buscados pela ID de conexão de serviço.

  "contributions": [
    {
      "id": "service-endpoint",
      "description": "Service endpoint type for Fabrikam connections",
      "type": "ms.vss-endpoint.service-endpoint-type",
      "targets": [ "ms.vss-endpoint.endpoint-types" ],
      "properties": {
        "name": "fabrikam",
        "displayName": "Fabrikam server connection",
        "url": {
          "displayName": "Server Url",
          "helpText": "Url for the Fabrikam server to connect to."
        },
        "dataSources": [
          {
            "name": "Fabrikam Projects",
            "endpointUrl": "{{endpoint.url}}api/projects/index",
            "resultSelector": "jsonpath:$[*].nm"
          }

        ],
        "authenticationSchemes": [
          {
            "type": "ms.vss-endpoint.endpoint-auth-scheme-token"
          },
          {
            "type": "ms.vss-endpoint.endpoint-auth-scheme-basic",
            "inputDescriptors": [
              {
                "id": "username",
                "name": "Username",
                "description": "Username",
                "inputMode": "textbox",
                "validation": {
                  "isRequired": false,
                  "dataType": "string"
                }
              },
              {
                "id": "password",
                "name": "Password",
                "description": "Password",
                "inputMode": "passwordbox",
                "isConfidential": true,
                "validation": {
                  "isRequired": false,
                  "dataType": "string"
                }
              }
            ]
          }

        ],
        "helpMarkDown": "<a href=\"url-to-documentation\" target=\"_blank\"><b>Learn More</b></a>"
      }
    },
  ],

Se você adicionou com êxito a contribuição de serviço, verá o ponto de extremidade da Fabrikam quando tentar adicionar um novo ponto de extremidade de serviço à sua organização.

Crie um ponto de extremidade de serviço usando o ponto de extremidade da Fabrikam.

Captura de tela da configuração do ponto de extremidade do serviço.

Gorjeta

Você pode adicionar inputDescriptors sem authenticationSchemes. Para obter mais informações, consulte Interface InputDescriptor.

Adicionar a contribuição da tarefa de compilação

Dentro da contributions matriz da etapa anterior, adicione o seguinte objeto ao final.

{
      "id": "build-task",
      "description": "Task with a dynamic property getting data from an endpoint REST data source",
      "type": "ms.vss-distributed-task.task",
      "targets": [ "ms.vss-distributed-task.tasks" ],
      "properties": {
        "name": "BuildTaskFolder"
      }
    }

A URL do ponto de extremidade dataSource é calculada a partir da URL do ponto de extremidade ou de uma URL fixa e alguns outros valores. Para este tutorial, esta chamada REST não retorna nada e destina-se a ser substituída por quaisquer chamadas REST que você deseja fazer ao seu serviço.

É possível usar outros parâmetros além da URL do ponto de extremidade para a URL REST, por exemplo, algumas propriedades do ponto final. Por exemplo, supondo que tivéssemos uma propriedade no ponto de extremidade chamada subscriptionId, a URL REST poderia usá-la com a seguinte sintaxe: $(endpoint.subscription).

Criar a tarefa de compilação

O task.json arquivo descreve sua tarefa de compilação.

Nota

Para mais informações, consulte os seguintes artigos:

Crie um task.json ficheiro no seu BuildTaskFolder diretório, se ainda não criou esta pasta, faça-o agora.

{
  "id": "6557a6d2-4caf-4247-99ea-5131286a8753",
  "name": "build-task",
  "friendlyName": "Build Task that uses the service endpoint",
  "description": "Task with a dynamic property getting data from an endpoint REST data source",
  "author": "francistotten",
  "helpMarkDown": "Replace with Markdown to show in help",
  "category": "Build",
  "visibility": [
    "Build",
    "Release"
  ],
  "demands": [],
  "version": {
    "Major": "0",
    "Minor": "1",
    "Patch": "1"
  },
  "minimumAgentVersion": "1.95.0",
  "instanceNameFormat": "Service Endpoint Build Task $(project)",
  "inputs": [
    {
      "name": "FabrikamService",
      "type": "connectedService:Fabrikam",
      "label": "Fabrikam service/server end point",
      "defaultValue": "",
      "required": true,
      "helpMarkDown": "Select the Fabrikam end point to use. If needed, select 'manage', and add a new service endpoint of type 'Fabrikam server connection'"
    },
    {
      "name": "project",
      "type": "pickList",
      "label": "Fabrikam Project",
      "required": true,
      "helpMarkDown": "Select the name of the Fabrikam Project to analyze.",
      "properties": {
        "EditableOptions": "True"
      }
    }
  ],
  "dataSourceBindings": [
    {
      "target": "project",
      "endpointId": "$(FabrikamService)",
      "dataSourceName": "Fabrikam Projects"
    }
  ],
  "execution": {
    "Node": {
      "target": "sample.js",
      "argumentFormat": ""
    },
    "PowerShell3": {
      "target": "sample.ps1"
    }
  }
}

task.json componentes

O FabrikamService objeto de entrada

Este campo é o primeiro do tipo connectedService:Fabrikam.connectedService expressa que é um tipo de ponto de extremidade e que Fabrikam é o nome do objeto.

O project objeto de entrada

Este campo é o segundo. É uma lista de opções.

  • Este campo é preenchido por uma chamada REST.
  • Os valores do campo "projeto" são retirados da fonte de dados REST "Projetos" do ponto de extremidade personalizado.
  • Expresso na dataSourceBindings matriz.
    • O destino é o nome do campo de tarefa de construção a ser preenchido ("projeto").
    • O endpointId é o nome do campo de tarefa de compilação que contém o tipo de ponto de extremidade personalizado.
    • A chamada REST é escolhida pelo dataSourceName.

Se você adicionou a Tarefa de compilação com êxito, agora deverá ver a Tarefa de compilação quando estiver adicionando tarefas a um pipeline de compilação.

Imagem do seletor de tarefas de compilação do ponto de extremidade de serviço.

Depois de adicionar a Tarefa de compilação ao seu pipeline, confirme se ela pode ver o ponto de extremidade da Fabrikam que você criou. A lista suspensa de projetos neste tutorial está em branco, pois não estamos usando um serviço real. Depois de substituir a Fabrikam pelo seu serviço, substitua a chamada Projects pela sua própria chamada de API REST para usar dados dinâmicos dentro da sua tarefa de compilação.

Imagem de configuração da tarefa de compilação do ponto de extremidade de serviço.

Autenticação

O esquema de autenticação em um ponto de extremidade de serviço determina as credenciais que seriam usadas para se conectar ao serviço externo. Para obter mais informações e ver os seguintes esquemas de autenticação, consulte a documentação dos esquemas de autenticação.

  • Autenticação básica
  • Autenticação baseada em tokens
  • Autenticação baseada em certificado
  • Sem autenticação

Próximos passos

Empacotar, publicar e instalar extensões