Criar um ponto de extremidade de serviço

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Os pontos de extremidade de serviço são uma forma que o Azure DevOps tem de se conectar a serviços ou sistemas 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
• Descrição
• Servidor URL
• Certificados ou tokens
• Nomes de usuário e senhas

As extensões podem 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.

Dica

Confira nossa documentação mais recente sobre o desenvolvimento de extensão usando o SDK da 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 e uma lista de opções, que tem valores preenchidos a partir da fonte de dados de ponto de extremidade REST.

Observação

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:

• 1. Crie o arquivo de manifesto de extensão
• 2. Crie o pipeline de tarefas de compilação, no arquivo task.json

Observação

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

Crie o arquivo de manifesto: vss-extension.json

O arquivo de manifesto define o ponto de extremidade personalizado e vincula ao 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 um ponto de extremidade de serviço
  • Visão geral da tarefa
  • Crie o arquivo de manifesto: vss-extension.json
    • Criar arquivo de manifesto básico
    • Adicionar a contribuição de ponto de extremidade personalizado
    • Adicionar a contribuição da tarefa de compilação
  • Criar a tarefa de compilação
    • task.json componentes
  • Autenticação
  • Próximas Etapas 
  • Artigos relacionados

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"
    }
  ]
}

Observação

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

Adicionar a contribuição de ponto de extremidade personalizado

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

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ê tiver adicionado com êxito a contribuição de serviço, verá o ponto de extremidade da Fabrikam ao 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.

Dica

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ê deseje 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 de extremidade. 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 build

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

Observação

Para obter mais informações, marcar os seguintes artigos:

• Referência de tarefa de compilação para localizar o esquema do arquivo json da tarefa de compilação
• Adicionar uma extensão de tarefa de pipelines personalizada
• Integrar tarefa de compilação

Crie um task.json arquivo em seu BuildTaskFolder diretório, se você ainda não criou essa pasta, faça isso 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,selecton '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

Esse 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 escolhas.

• Este campo é preenchido por uma chamada REST.
• Os valores do campo "project" são retirados da fonte de dados REST "Projects" do ponto de extremidade personalizado.
• Expresso na dataSourceBindings matriz.
  • O destino é o nome do campo de tarefa de compilaçã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 Criação com êxito, agora deverá ver a Tarefa de Criação quando estiver adicionando tarefas a um pipeline de compilação.

Depois de adicionar a Tarefa de Criação ao 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 serviço, substitua a chamada Projetos por sua própria chamada de API REST para usar dados dinâmicos dentro da tarefa de compilaçã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 de esquemas de autenticação.

• Autenticação Básica
• Autenticação baseada em token
• Autenticação baseada em certificado
• Sem autenticação

Próximas etapas

Empacotar, publicar e instalar extensões

Artigos relacionados

• Testar e depurar extensões
• Desenvolver uma extensão web
• Adicionar um decorador de pipeline