Atividade da Web no Azure Data FactoryWeb activity in Azure Data Factory

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

A atividade da Web pode ser usada para chamar um ponto de extremidade REST personalizado de um pipeline do Data Factory.Web Activity can be used to call a custom REST endpoint from a Data Factory pipeline. Você pode passar conjuntos de dados e serviços vinculados a serem consumidos e acessados pela atividade.You can pass datasets and linked services to be consumed and accessed by the activity.

Observação

A atividade da Web também pode invocar URLs que são hospedadas em uma rede virtual privada aproveitando o runtime de integração auto-hospedada.Web Activity is supported for invoking URLs that are hosted in a private virtual network as well by leveraging self-hosted integration runtime. O runtime de integração deve ter uma linha de visão para o ponto de extremidade da URL.The integration runtime should have a line of sight to the URL endpoint.

Observação

O tamanho máximo de carga de resposta de saída com suporte é 4 MB.The maximum supported output response payload size is 4 MB.

SintaxeSyntax

{
   "name":"MyWebActivity",
   "type":"WebActivity",
   "typeProperties":{
      "method":"Post",
      "url":"<URLEndpoint>",
      "connectVia": {
          "referenceName": "<integrationRuntimeName>",
          "type": "IntegrationRuntimeReference"
      }
      "headers":{
         "Content-Type":"application/json"
      },
      "authentication":{
         "type":"ClientCertificate",
         "pfx":"****",
         "password":"****"
      },
      "datasets":[
         {
            "referenceName":"<ConsumedDatasetName>",
            "type":"DatasetReference",
            "parameters":{
               ...
            }
         }
      ],
      "linkedServices":[
         {
            "referenceName":"<ConsumedLinkedServiceName>",
            "type":"LinkedServiceReference"
         }
      ]
   }
}

Propriedades de tipoType properties

PropriedadeProperty DescriçãoDescription Valores permitidosAllowed values ObrigatórioRequired
namename Nome da atividade da WebName of the web activity StringString SimYes
typetype Deve ser definido como WebActivity.Must be set to WebActivity. StringString SimYes
methodmethod Método da API REST para o ponto de extremidade de destino.Rest API method for the target endpoint. Cadeia de caracteres.String.

Tipos com suporte: "GET", "POST", "PUT"Supported Types: "GET", "POST", "PUT"
SimYes
urlurl Ponto de extremidade de destino e o caminhoTarget endpoint and path Cadeia de caracteres (ou expressão com um resultType de cadeia de caracteres).String (or expression with resultType of string). A atividade atingirá o tempo limite em 1 minuto com um erro se não receber uma resposta do ponto de extremidade.The activity will timeout at 1 minute with an error if it does not receive a response from the endpoint. SimYes
headersheaders Cabeçalhos que são enviados para a solicitação.Headers that are sent to the request. Por exemplo, para definir o idioma e o tipo em uma solicitação: "headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }.For example, to set the language and type on a request: "headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }. Cadeia de caracteres (ou expressão com um resultType de cadeia de caracteres)String (or expression with resultType of string) Sim, o cabeçalho Content-Type é necessário.Yes, Content-type header is required. "headers":{ "Content-Type":"application/json"}
bodybody Representa o conteúdo enviado para o ponto de extremidade.Represents the payload that is sent to the endpoint. Cadeia de caracteres (ou expressão com um resultType de cadeia de caracteres).String (or expression with resultType of string).

Consulte o esquema da carga de solicitação na seção Esquema de carga de solicitação.See the schema of the request payload in Request payload schema section.
Necessário para os métodos PUT/POST.Required for POST/PUT methods.
autenticaçãoauthentication Método de autenticação usado para chamar o ponto de extremidade.Authentication method used for calling the endpoint. Os tipos com suporte são "Basic ou ClientCertificate."Supported Types are "Basic, or ClientCertificate." Para obter mais informações, consulte a seção autenticação .For more information, see Authentication section. Se a autenticação não for necessária, exclua essa propriedade.If authentication is not required, exclude this property. Cadeia de caracteres (ou expressão com um resultType de cadeia de caracteres)String (or expression with resultType of string) NãoNo
conjuntos de dadosdatasets Lista de conjuntos de dados passados para o ponto de extremidade.List of datasets passed to the endpoint. Matriz de referências do conjunto de dados.Array of dataset references. Pode ser uma matriz vazia.Can be an empty array. SimYes
linkedServiceslinkedServices Lista de serviços vinculados passado ao ponto de extremidade.List of linked services passed to endpoint. Matriz de referências de serviço vinculado.Array of linked service references. Pode ser uma matriz vazia.Can be an empty array. SimYes
connectViaconnectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados.The integration runtime to be used to connect to the data store. Você pode usar o tempo de execução de integração do Azure ou o tempo de execução de integração auto-hospedado (se o armazenamento de dados estiver em uma rede privada).You can use the Azure integration runtime or the self-hosted integration runtime (if your data store is in a private network). Se essa propriedade não for especificada, o serviço usará o tempo de execução de integração do Azure padrão.If this property isn't specified, the service uses the default Azure integration runtime. A referência do Integration Runtime.The integration runtime reference. NãoNo

Observação

Os pontos de extremidade REST que invoca a atividade da Web invoca devem retornar para uma resposta do JSON de tipo.REST endpoints that the web activity invokes must return a response of type JSON. A atividade atingirá o tempo limite em 1 minuto com um erro se não receber uma resposta do ponto de extremidade.The activity will timeout at 1 minute with an error if it does not receive a response from the endpoint.

A tabela a seguir mostra os requisitos para o conteúdo JSON:The following table shows the requirements for JSON content:

Tipo de valorValue type Corpo da solicitaçãoRequest body Corpo da respostaResponse body
Objeto JSONJSON object Com suporteSupported Com suporteSupported
Matriz JSONJSON array Com suporteSupported
(No momento, matrizes JSON não funcionam como resultado de um bug.(At present, JSON arrays don't work as a result of a bug. A correção está em andamento.)A fix is in progress.)
Sem suporteUnsupported
Valor JSONJSON value Com suporteSupported Sem suporteUnsupported
Tipo não-JSONNon-JSON type Sem suporteUnsupported Sem suporteUnsupported

AutenticaçãoAuthentication

Abaixo estão os tipos de autenticação com suporte na atividade da Web.Below are the supported authentication types in the web activity.

NenhumNone

Se a autenticação não for necessária, não inclua a propriedade "authentication".If authentication is not required, do not include the "authentication" property.

BásicoBasic

Especifique o nome de usuário e senha a serem usados com a autenticação básica.Specify user name and password to use with the basic authentication.

"authentication":{
   "type":"Basic",
   "username":"****",
   "password":"****"
}

Certificado do clienteClient certificate

Especifique o conteúdo codificado em base64 de um arquivo PFX e a senha.Specify base64-encoded contents of a PFX file and the password.

"authentication":{
   "type":"ClientCertificate",
   "pfx":"****",
   "password":"****"
}

Identidade GerenciadaManaged Identity

Especifique o URI do recurso para o qual o token de acesso será solicitado usando a identidade gerenciada para o data factory.Specify the resource uri for which the access token will be requested using the managed identity for the data factory. Para chamar a API de Gerenciamento de Recursos do Azure, use https://management.azure.com/.To call the Azure Resource Management API, use https://management.azure.com/. Para obter mais informações sobre como identidades gerenciadas funcionam, confira a página de visão geral de identidades gerenciadas para recursos do Azure.For more information about how managed identities works see the managed identities for Azure resources overview page.

"authentication": {
    "type": "MSI",
    "resource": "https://management.azure.com/"
}

Observação

Se sua data factory estiver configurada com um repositório git, você deverá armazenar suas credenciais no Azure Key Vault para usar a autenticação básica ou de certificado do cliente.If your data factory is configured with a git repository, you must store your credentials in Azure Key Vault to use basic or client certificate authentication. Azure Data Factory não armazena senhas no git.Azure Data Factory doesn't store passwords in git.

Solicitar esquema de cargaRequest payload schema

Quando você usa o método PUT/POST, a propriedade body representa a carga que é enviada para o ponto de extremidade.When you use the POST/PUT method, the body property represents the payload that is sent to the endpoint. Você pode passar serviços vinculados e conjuntos de dados como parte da carga.You can pass linked services and datasets as part of the payload. Aqui está o esquema para a carga:Here is the schema for the payload:

{
    "body": {
        "myMessage": "Sample",
        "datasets": [{
            "name": "MyDataset1",
            "properties": {
                ...
            }
        }],
        "linkedServices": [{
            "name": "MyStorageLinkedService1",
            "properties": {
                ...
            }
        }]
    }
}

ExemploExample

Neste exemplo, a atividade da Web no pipeline chama um ponto de extremidade REST.In this example, the web activity in the pipeline calls a REST end point. Ele passa um serviço vinculado do SQL do Azure e um conjunto de dados SQL do Azure para o ponto de extremidade.It passes an Azure SQL linked service and an Azure SQL dataset to the endpoint. O ponto de extremidade REST usa a cadeia de conexão SQL do Azure para se conectar ao SQL Server lógico e retorna o nome da instância do SQL Server.The REST end point uses the Azure SQL connection string to connect to the logical SQL server and returns the name of the instance of SQL server.

Definição de pipelinePipeline definition

{
    "name": "<MyWebActivityPipeline>",
    "properties": {
        "activities": [
            {
                "name": "<MyWebActivity>",
                "type": "WebActivity",
                "typeProperties": {
                    "method": "Post",
                    "url": "@pipeline().parameters.url",
                    "headers": {
                        "Content-Type": "application/json"
                    },
                    "authentication": {
                        "type": "ClientCertificate",
                        "pfx": "*****",
                        "password": "*****"
                    },
                    "datasets": [
                        {
                            "referenceName": "MySQLDataset",
                            "type": "DatasetReference",
                            "parameters": {
                                "SqlTableName": "@pipeline().parameters.sqlTableName"
                            }
                        }
                    ],
                    "linkedServices": [
                        {
                            "referenceName": "SqlLinkedService",
                            "type": "LinkedServiceReference"
                        }
                    ]
                }
            }
        ],
        "parameters": {
            "sqlTableName": {
                "type": "String"
            },
            "url": {
                "type": "String"
            }
        }
    }
}

Valores de parâmetro do pipelinePipeline parameter values

{
    "sqlTableName": "department",
    "url": "https://adftes.azurewebsites.net/api/execute/running"
}

Código do ponto de extremidade de serviço WebWeb service endpoint code


[HttpPost]
public HttpResponseMessage Execute(JObject payload)
{
    Trace.TraceInformation("Start Execute");

    JObject result = new JObject();
    result.Add("status", "complete");

    JArray datasets = payload.GetValue("datasets") as JArray;
    result.Add("sinktable", datasets[0]["properties"]["typeProperties"]["tableName"].ToString());

    JArray linkedServices = payload.GetValue("linkedServices") as JArray;
    string connString = linkedServices[0]["properties"]["typeProperties"]["connectionString"].ToString();

    System.Data.SqlClient.SqlConnection sqlConn = new System.Data.SqlClient.SqlConnection(connString);

    result.Add("sinkServer", sqlConn.DataSource);

    Trace.TraceInformation("Stop Execute");

    return this.Request.CreateResponse(HttpStatusCode.OK, result);
}

Próximas etapasNext steps

Consulte outras atividades de fluxo de controle com suporte pelo Data Factory:See other control flow activities supported by Data Factory: