Guida introduttiva: Creare una data factory di Azure e una pipeline usando l'API RESTQuickstart: Create an Azure data factory and pipeline by using the REST API

Azure Data Factory è un servizio di integrazione di dati basato sul cloud che consente di creare flussi di lavoro basati sui dati nel cloud per orchestrare e automatizzare lo spostamento e la trasformazione dei dati stessi.Azure Data Factory is a cloud-based data integration service that allows you to create data-driven workflows in the cloud for orchestrating and automating data movement and data transformation. Usando Azure Data Factory è possibile creare e pianificare flussi di lavoro (denominati pipeline) basati sui dati che possono inserire dati da archivi diversi, elaborarli e trasformarli tramite servizi di calcolo come Hadoop di Azure HDInsight, Spark, Azure Data Lake Analytics e Azure Machine Learning e pubblicare l'output in archivi come Azure SQL Data Warehouse per l'uso da parte di applicazioni di business intelligence (BI).Using Azure Data Factory, you can create and schedule data-driven workflows (called pipelines) that can ingest data from disparate data stores, process/transform the data by using compute services such as Azure HDInsight Hadoop, Spark, Azure Data Lake Analytics, and Azure Machine Learning, and publish output data to data stores such as Azure SQL Data Warehouse for business intelligence (BI) applications to consume.

Questa guida introduttiva descrive come usare l'API REST per creare una data factory di Azure.This quickstart describes how to use REST API to create an Azure data factory. La pipeline in questa data factory copia i dati da un percorso a un altro nell'archiviazione BLOB di Azure.The pipeline in this data factory copies data from one location to another location in an Azure blob storage.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.If you don't have an Azure subscription, create a free account before you begin.

PrerequisitiPrerequisites

Nota

Questo articolo è stato aggiornato per usare il nuovo modulo Az di Azure PowerShell.This article has been updated to use the new Azure PowerShell Az module. È comunque possibile usare il modulo AzureRM, che continuerà a ricevere correzioni di bug almeno fino a dicembre 2020.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. Per altre informazioni sul nuovo modulo Az e sulla compatibilità di AzureRM, vedere Introduzione del nuovo modulo Az di Azure PowerShell.To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Per istruzioni sull'installazione del modulo Az, vedere Installare Azure PowerShell.For Az module installation instructions, see Install Azure PowerShell.

  • Sottoscrizione di Azure.Azure subscription. Se non si ha una sottoscrizione, è possibile creare un account di valutazione gratuito.If you don't have a subscription, you can create a free trial account.
  • Account di archiviazione di Azure.Azure Storage account. Usare l'archivio BLOB come archivio dati di origine e sink.You use the blob storage as source and sink data store. Se non si ha un account di archiviazione di Azure, vedere l'articolo Creare un account di archiviazione per informazioni su come crearne uno.If you don't have an Azure storage account, see the Create a storage account article for steps to create one.
  • Creare un contenitore BLOB in Archiviazione BLOB, creare una cartella di input nel contenitore e caricare alcuni file nella cartella.Create a blob container in Blob Storage, create an input folder in the container, and upload some files to the folder. È possibile usare strumenti come Azure Storage Explorer per connettersi all'archivio BLOB di Azure, creare un contenitore BLOB, caricare il file di input e verificare il file di output.You can use tools such as Azure Storage explorer to connect to Azure Blob storage, create a blob container, upload input file, and verify the output file.
  • Installare Azure PowerShell.Install Azure PowerShell. Seguire le istruzioni in Come installare e configurare Azure PowerShell.Follow the instructions in How to install and configure Azure PowerShell. Questa guida introduttiva usa PowerShell per richiamare le chiamate API REST.This quickstart uses PowerShell to invoke REST API calls.
  • Creare un'applicazione in Azure Active Directory seguendo queste istruzioni.Create an application in Azure Active Directory following this instruction. Annotare i valori seguenti, da usare nei passaggi successivi: ID applicazione, chiave di autenticazione e ID tenant.Make note of the following values that you use in later steps: application ID, authentication key, and tenant ID. Assegnare l'applicazione al ruolo Collaboratore.Assign application to "Contributor" role.

Configurare le variabili globaliSet global variables

  1. Avviare PowerShell.Launch PowerShell. Tenere aperto Azure PowerShell fino al termine di questa guida introduttiva.Keep Azure PowerShell open until the end of this quickstart. Se si chiude e si riapre, sarà necessario eseguire di nuovo questi comandi.If you close and reopen, you need to run the commands again.

    Eseguire questo comando e immettere il nome utente e la password usati per accedere al portale di Azure:Run the following command, and enter the user name and password that you use to sign in to the Azure portal:

    Connect-AzAccount
    

    Eseguire questo comando per visualizzare tutte le sottoscrizioni per l'account:Run the following command to view all the subscriptions for this account:

    Get-AzSubscription
    

    Eseguire il comando seguente per selezionare la sottoscrizione da usare.Run the following command to select the subscription that you want to work with. Sostituire SubscriptionId con l'ID della sottoscrizione di Azure:Replace SubscriptionId with the ID of your Azure subscription:

    Select-AzSubscription -SubscriptionId "<SubscriptionId>"
    
  2. Eseguire i comandi seguenti dopo aver sostituito i segnaposto con i propri valori, per impostare le variabili globali da usare nei passaggi successivi.Run the following commands after replacing the places-holders with your own values, to set global variables to be used in later steps.

    $tenantID = "<your tenant ID>"
    $appId = "<your application ID>"
    $authKey = "<your authentication key for the application>"
    $subsId = "<your subscription ID to create the factory>"
    $resourceGroup = "<your resource group to create the factory>"
    $dataFactoryName = "<specify the name of data factory to create. It must be globally unique.>"
    $apiVersion = "2018-06-01"
    

Eseguire l'autenticazione con Azure ADAuthenticate with Azure AD

Eseguire i comandi seguenti per autenticarsi in Azure Active Directory (AAD):Run the following commands to authenticate with Azure Active Directory (AAD):

$AuthContext = [Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext]"https://login.microsoftonline.com/${tenantId}"
$cred = New-Object -TypeName Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential -ArgumentList ($appId, $authKey)
$result = $AuthContext.AcquireToken("https://management.core.windows.net/", $cred)
$authHeader = @{
'Content-Type'='application/json'
'Accept'='application/json'
'Authorization'=$result.CreateAuthorizationHeader()
}

Creare una data factoryCreate a data factory

Eseguire i comandi seguenti per creare una data factory:Run the following commands to create a data factory:

$request = "https://management.azure.com/subscriptions/${subsId}/resourceGroups/${resourceGroup}/providers/Microsoft.DataFactory/factories/${dataFactoryName}?api-version=${apiVersion}"
$body = @"
{
    "name": "$dataFactoryName",
    "location": "East US",
    "properties": {},
    "identity": {
        "type": "SystemAssigned"
    }
}
"@
$response = Invoke-RestMethod -Method PUT -Uri $request -Header $authHeader -Body $body
$response | ConvertTo-Json

Tenere presente quanto segue:Note the following points:

  • È necessario specificare un nome univoco globale per l'istanza di Azure Data Factory.The name of the Azure data factory must be globally unique. Se viene visualizzato l'errore seguente, modificare il nome e riprovare.If you receive the following error, change the name and try again.

    Data factory name "ADFv2QuickStartDataFactory" is not available.
    
  • Per un elenco di aree di Azure in cui Data Factory è attualmente disponibile, selezionare le aree di interesse nella pagina seguente, quindi espandere Analytics per individuare Data Factory: Prodotti disponibili in base all'area.For a list of Azure regions in which Data Factory is currently available, select the regions that interest you on the following page, and then expand Analytics to locate Data Factory: Products available by region. Gli archivi dati (Archiviazione di Azure, database SQL di Azure e così via) e le risorse di calcolo (HDInsight e così via) usati dalla data factory possono trovarsi in altre aree.The data stores (Azure Storage, Azure SQL Database, etc.) and computes (HDInsight, etc.) used by data factory can be in other regions.

Ecco la risposta di esempio:Here is the sample response:

{
    "name": "<dataFactoryName>",
    "tags": {
    },
    "properties":  {
        "provisioningState":  "Succeeded",
        "loggingStorageAccountKey":  "**********",
        "createTime":  "2017-09-14T06:22:59.9106216Z",
        "version":  "2018-06-01"
    },
    "identity":  {
        "type":  "SystemAssigned",
        "principalId":  "<service principal ID>",
        "tenantId":  "<tenant ID>"
    },
    "id":  "dataFactoryName",
    "type":  "Microsoft.DataFactory/factories",
    "location":  "East US"
}

Creare servizi collegatiCreate linked services

Si creano servizi collegati in una data factory per collegare gli archivi dati e i servizi di calcolo alla data factory.You create linked services in a data factory to link your data stores and compute services to the data factory. In questa guida introduttiva è necessario creare solo un servizio collegato di Archiviazione di Azure come archivio di origine e sink della copia, denominato "AzureStorageLinkedService" nell'esempio.In this quickstart, you only need create one Azure Storage linked service as both copy source and sink store, named "AzureStorageLinkedService" in the sample.

Eseguire i comandi seguenti per creare un servizio collegato denominato AzureStorageLinkedService:Run the following commands to create a linked service named AzureStorageLinkedService:

Sostituire <accountName> e <accountKey> con il nome e la chiave dell'account di archiviazione di Azure prima di eseguire i comandi.Replace <accountName> and <accountKey> with name and key of your Azure storage account before executing the commands.

$request = "https://management.azure.com/subscriptions/${subsId}/resourceGroups/${resourceGroup}/providers/Microsoft.DataFactory/factories/${dataFactoryName}/linkedservices/AzureStorageLinkedService?api-version=${apiVersion}"
$body = @"
{
    "name": "AzureStorageLinkedService",
    "properties": {
        "type": "AzureStorage",
        "typeProperties": {
            "connectionString": {
                "value": "DefaultEndpointsProtocol=https;AccountName=<accountName>;AccountKey=<accountKey>",
                "type": "SecureString"
            }
        }
    }
}
"@
$response = Invoke-RestMethod -Method PUT -Uri $request -Header $authHeader -Body $body
$response | ConvertTo-Json

Di seguito è riportato l'output di esempio:Here is the sample output:

{
    "id":  "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.DataFactory/factories/<dataFactoryName>/linkedservices/AzureStorageLinkedService",
    "name":  "AzureStorageLinkedService",
    "properties":  {
        "type":  "AzureStorage",
        "typeProperties":  {
            "connectionString":  "@{value=**********; type=SecureString}"
        }
    },
    "etag":  "0000c552-0000-0000-0000-59b1459c0000"
}

Creare set di datiCreate datasets

È necessario definire un set di dati che rappresenta i dati da copiare da un'origine a un sink.You define a dataset that represents the data to copy from a source to a sink. In questo esempio il set di dati del BLOB fa riferimento al servizio collegato Archiviazione di Azure creato nel passaggio precedente.In this example, this Blob dataset refers to the Azure Storage linked service you create in the previous step. Il set di dati accetta un parametro il cui valore è impostato in un'attività che utilizza il set di dati.The dataset takes a parameter whose value is set in an activity that consumes the dataset. Il parametro viene usato per costruire la proprietà "folderPath" che punta al percorso in cui si trovano e sono archiviati i dati.The parameter is used to construct the "folderPath" pointing to where the data resides/stored.

$request = "https://management.azure.com/subscriptions/${subsId}/resourceGroups/${resourceGroup}/providers/Microsoft.DataFactory/factories/${dataFactoryName}/datasets/BlobDataset?api-version=${apiVersion}"
$body = @"
{
    "name": "BlobDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": {
                "value": "@{dataset().path}",
                "type": "Expression"
            }
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "path": {
                "type": "String"
            }
        }
    }
}
"@
$response = Invoke-RestMethod -Method PUT -Uri $request -Header $authHeader -Body $body
$response | ConvertTo-Json

Di seguito è riportato l'output di esempio:Here is the sample output:

{
    "id":  "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.DataFactory/factories/<dataFactoryName>/datasets/BlobDataset",
    "name":  "BlobDataset",
    "properties":  {
        "type":  "AzureBlob",
        "typeProperties":  {
            "folderPath":  "@{value=@{dataset().path}; type=Expression}"
        },
        "linkedServiceName":  {
            "referenceName":  "AzureStorageLinkedService",
            "type":  "LinkedServiceReference"
        },
        "parameters":  {
            "path":  "@{type=String}"
        }
    },
    "etag":  "0000c752-0000-0000-0000-59b1459d0000"
}

Creare una pipelineCreate pipeline

In questo esempio la pipeline contiene un'attività e accetta due parametri, il percorso del BLOB di input e il percorso del BLOB di output.In this example, this pipeline contains one activity and takes two parameters - input blob path and output blob path. I valori per questi parametri vengono impostati all'esecuzione/attivazione della pipeline.The values for these parameters are set when the pipeline is triggered/run. L'attività di copia fa riferimento allo stesso set di dati del BLOB creato nel passaggio precedente come input e output.The copy activity refers to the same blob dataset created in the previous step as input and output. Quando il set di dati viene usato come set di dati di input, viene specificato il percorso di input.When the dataset is used as an input dataset, input path is specified. Quando il set di dati viene usato come set di dati di output, viene specificato il percorso di output.And, when the dataset is used as an output dataset, the output path is specified.

$request = "https://management.azure.com/subscriptions/${subsId}/resourceGroups/${resourceGroup}/providers/Microsoft.DataFactory/factories/${dataFactoryName}/pipelines/Adfv2QuickStartPipeline?api-version=${apiVersion}"
$body = @"
{
    "name": "Adfv2QuickStartPipeline",
    "properties": {
        "activities": [
            {
                "name": "CopyFromBlobToBlob",
                "type": "Copy",
                "inputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.inputPath"
                        },
                    "type": "DatasetReference"
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.outputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "typeProperties": {
                    "source": {
                        "type": "BlobSource"
                    },
                    "sink": {
                        "type": "BlobSink"
                    }
                }
            }
        ],
        "parameters": {
            "inputPath": {
                "type": "String"
            },
            "outputPath": {
                "type": "String"
            }
        }
    }
}
"@
$response = Invoke-RestMethod -Method PUT -Uri $request -Header $authHeader -Body $body
$response | ConvertTo-Json

Di seguito è riportato l'output di esempio:Here is the sample output:

{
    "id":  "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.DataFactory/factories/<dataFactoryName>/pipelines/Adfv2QuickStartPipeline",
    "name":  "Adfv2QuickStartPipeline",
    "properties":  {
        "activities":  [
            "@{name=CopyFromBlobToBlob; type=Copy; inputs=System.Object[]; outputs=System.Object[]; typeProperties=}"
        ],
        "parameters":  {
            "inputPath":  "@{type=String}",
            "outputPath":  "@{type=String}"
        }
    },
    "etag":  "0000c852-0000-0000-0000-59b1459e0000"
}

Creare l'esecuzione della pipelineCreate pipeline run

In questo passaggio si impostano i valori dei parametri inputPath e outputPath specificati nella pipeline con gli effettivi valori dei percorsi dei BLOB di origine e sink e quindi si attiva un'esecuzione della pipeline.In this step, you set values of inputPath and outputPath parameters specified in pipeline with the actual values of source and sink blob paths, and trigger a pipeline run. L'ID di esecuzione della pipeline restituito nel corpo della risposta viene usato nel monitoraggio successivo dell'API.The pipeline run ID returned in the response body is used in later monitoring API.

Sostituire il valore di inputPath e outputPath con il percorso dei BLOB di origine e sink per copiare i dati nelle due direzioni prima di salvare il file.Replace value of inputPath and outputPath with your source and sink blob path to copy data from and to before saving the file.

$request = "https://management.azure.com/subscriptions/${subsId}/resourceGroups/${resourceGroup}/providers/Microsoft.DataFactory/factories/${dataFactoryName}/pipelines/Adfv2QuickStartPipeline/createRun?api-version=${apiVersion}"
$body = @"
{
    "inputPath": "<the path to existing blob(s) to copy data from, e.g. containername/path>",
    "outputPath": "<the blob path to copy data to, e.g. containername/path>"
}
"@
$response = Invoke-RestMethod -Method POST -Uri $request -Header $authHeader -Body $body
$response | ConvertTo-Json
$runId = $response.runId

Di seguito è riportato l'output di esempio:Here is the sample output:

{
    "runId":  "2f26be35-c112-43fa-9eaa-8ba93ea57881"
}

Monitorare la pipelineMonitor pipeline

  1. Eseguire lo script seguente per verificare continuamente lo stato di esecuzione della pipeline fino al termine della copia dei dati.Run the following script to continuously check the pipeline run status until it finishes copying the data.

    $request = "https://management.azure.com/subscriptions/${subsId}/resourceGroups/${resourceGroup}/providers/Microsoft.DataFactory/factories/${dataFactoryName}/pipelineruns/${runId}?api-version=${apiVersion}"
    while ($True) {
        $response = Invoke-RestMethod -Method GET -Uri $request -Header $authHeader
        Write-Host  "Pipeline run status: " $response.Status -foregroundcolor "Yellow"
    
        if ($response.Status -eq "InProgress") {
            Start-Sleep -Seconds 15
        }
        else {
            $response | ConvertTo-Json
            break
        }
    }
    

    Di seguito è riportato l'output di esempio:Here is the sample output:

    {
        "key":  "000000000-0000-0000-0000-00000000000",
        "timestamp":  "2017-09-07T13:12:39.5561795Z",
        "runId":  "000000000-0000-0000-0000-000000000000",
        "dataFactoryName":  "<dataFactoryName>",
        "pipelineName":  "Adfv2QuickStartPipeline",
        "parameters":  [
            "inputPath: <inputBlobPath>",
            "outputPath: <outputBlobPath>"
        ],
        "parametersCount":  2,
        "parameterNames":  [
            "inputPath",
            "outputPath"
        ],
        "parameterNamesCount":  2,
        "parameterValues":  [
            "<inputBlobPath>",
            "<outputBlobPath>"
        ],
        "parameterValuesCount":  2,
        "runStart":  "2017-09-07T13:12:00.3710792Z",
        "runEnd":  "2017-09-07T13:12:39.5561795Z",
        "durationInMs":  39185,
        "status":  "Succeeded",
        "message":  ""
    }
    
  2. Eseguire lo script seguente per recuperare i dettagli sull'esecuzione dell'attività di copia, ad esempio le dimensioni dei dati letti/scritti.Run the following script to retrieve copy activity run details, for example, size of the data read/written.

    $request = "https://management.azure.com/subscriptions/${subsId}/resourceGroups/${resourceGroup}/providers/Microsoft.DataFactory/factories/${dataFactoryName}/pipelineruns/${runId}/activityruns?api-version=${apiVersion}&startTime="+(Get-Date).ToString('yyyy-MM-dd')+"&endTime="+(Get-Date).AddDays(1).ToString('yyyy-MM-dd')+"&pipelineName=Adfv2QuickStartPipeline"
    $response = Invoke-RestMethod -Method GET -Uri $request -Header $authHeader
    $response | ConvertTo-Json
    

    Di seguito è riportato l'output di esempio:Here is the sample output:

    {
        "value":  [
            {
                "id":  "000000000-0000-0000-0000-00000000000",
                "timestamp":  "2017-09-07T13:12:38.4780542Z",
                "pipelineRunId":  "000000000-0000-00000-0000-0000000000000",
                "pipelineName":  "Adfv2QuickStartPipeline",
                "status":  "Succeeded",
                "failureType":  "",
                "linkedServiceName":  "",
                "activityName":  "CopyFromBlobToBlob",
                "activityType":  "Copy",
                "activityStart":  "2017-09-07T13:12:02.3299261Z",
                "activityEnd":  "2017-09-07T13:12:38.4780542Z",
                "duration":  36148,
                "input":  "@{source=; sink=}",
                "output":  "@{dataRead=331452208; dataWritten=331452208; copyDuration=22; throughput=14712.9; errors=System.Object[]; effectiveIntegrationRuntime=DefaultIntegrationRuntime (West US); usedDataIntegrationUnits=2; billedDuration=22}",
                "error":  "@{errorCode=; message=; failureType=; target=CopyFromBlobToBlob}"
            }
        ]
    }
    

Verificare l'outputVerify the output

Usare Azure Storage Explorer per verificare che i BLOB siano stati copiati in "outputBlobPath" da "inputBlobPath", come specificato durante la creazione dell'esecuzione della pipeline.Use Azure Storage explorer to check the blob(s) is copied to "outputBlobPath" from "inputBlobPath" as you specified when creating a pipeline run.

Pulire le risorseClean up resources

È possibile eseguire la pulizia delle risorse create nel corso della guida introduttiva in due modi.You can clean up the resources that you created in the Quickstart in two ways. Si può eliminare il gruppo di risorse di Azure, in modo da includere tutte le risorse del gruppo.You can delete the Azure resource group, which includes all the resources in the resource group. Se invece si vogliono mantenere intatte le altre risorse, eliminare solo la data factory creata in questa esercitazione.If you want to keep the other resources intact, delete only the data factory you created in this tutorial.

Eseguire il comando seguente per eliminare l'intero gruppo di risorse:Run the following command to delete the entire resource group:

Remove-AzResourceGroup -ResourceGroupName $resourcegroupname

Eseguire il comando seguente per eliminare solo la data factory:Run the following command to delete only the data factory:

Remove-AzDataFactoryV2 -Name "<NameOfYourDataFactory>" -ResourceGroupName "<NameOfResourceGroup>"

Passaggi successiviNext steps

La pipeline in questo esempio copia i dati da una posizione a un'altra in un archivio BLOB di Azure.The pipeline in this sample copies data from one location to another location in an Azure blob storage. Per informazioni sull'uso di Data Factory in più scenari, fare riferimento alle esercitazioni.Go through the tutorials to learn about using Data Factory in more scenarios.