Introduzione ad Azure Data Lake Analytics con API REST

Informazioni sull'uso delle API REST WebHDFS e delle API REST di Data Lake Analytics per gestire gli account, i processi e il catalogo di Data Lake Analytics.

Prerequisiti

Eseguire l'autenticazione con Azure Active Directory

Per l'autenticazione con Azure Active Directory è possibile procedere in due modi.

Autenticazione dell'utente finale (interattiva)

Con questo metodo, l'applicazione richiede all'utente di accedere e tutte le operazioni vengono eseguite nel contesto utente.

Eseguire questa procedura per l'autenticazione interattiva:

  1. Tramite l'applicazione, reindirizzare l'utente all'URL seguente:

     https://login.microsoftonline.com/<TENANT-ID>/oauth2/authorize?client_id=<CLIENT-ID>&response_type=code&redirect_uri=<REDIRECT-URI>
    
    Nota

    <REDIRECT-URI> deve essere codificato per essere usato in un URL. Per https://localhost, usare quindi https%3A%2F%2Flocalhost

    Per questa esercitazione, è possibile sostituire i valori segnaposto nell'URL precedente e incollare quest'ultimo nella barra degli indirizzi di un web browser. Si verrà reindirizzati per l'autenticazione tramite l'accesso ad Azure. Dopo aver eseguito correttamente l'accesso, la risposta verrà visualizzata nella barra degli indirizzi del browser. La risposta sarà nel formato seguente:

     http://localhost/?code=<AUTHORIZATION-CODE>&session_state=<GUID>
    
  2. Acquisire il codice di autorizzazione dalla risposta. Per questa esercitazione, è possibile copiare il codice di autorizzazione dalla barra degli indirizzi del web browser e passarla nella richiesta POST all'endpoint di token come illustrato di seguito:

     curl -X POST https://login.microsoftonline.com/<TENANT-ID>/oauth2/token \
     -F redirect_uri=<REDIRECT-URI> \
     -F grant_type=authorization_code \
     -F resource=https://management.core.windows.net/ \
     -F client_id=<CLIENT-ID> \
     -F code=<AUTHORIZATION-CODE>
    
    Nota

    In questo caso non è necessario codificare <REDIRECT-URI>.

  3. La risposta è un oggetto JSON che contiene un token di accesso (ad esempio, "access_token": "<ACCESS_TOKEN>") e un token di aggiornamento (ad esempio, "refresh_token": "<REFRESH_TOKEN>"). L'applicazione usa il token di accesso quando si accede all'Archivio Azure Data Lake e il token di aggiornamento quando un token di accesso scade per ottenerne un altro.

     {"token_type":"Bearer","scope":"user_impersonation","expires_in":"3599","expires_on":"1461865782","not_before":    "1461861882","resource":"https://management.core.windows.net/","access_token":"<REDACTED>","refresh_token":"<REDACTED>","id_token":"<REDACTED>"}
    
  4. Quando il token di accesso scade, è possibile richiederne uno nuovo tramite il token di aggiornamento come illustrato di seguito:

     curl -X POST https://login.microsoftonline.com/<TENANT-ID>/oauth2/token  \
          -F grant_type=refresh_token \
          -F resource=https://management.core.windows.net/ \
          -F client_id=<CLIENT-ID> \
          -F refresh_token=<REFRESH-TOKEN>
    

Per altre informazioni sull'autenticazione utente interattiva, vedere Flusso di concessione del codice di autorizzazione.

Autenticazione da servizio a servizio (non interattiva)

Con questo metodo, l'applicazione fornisce le proprie credenziali per eseguire le operazioni. A tale scopo è necessario inviare una richiesta POST come la seguente:

curl -X POST https://login.microsoftonline.com/<TENANT-ID>/oauth2/token  \
  -F grant_type=client_credentials \
  -F resource=https://management.core.windows.net/ \
  -F client_id=<CLIENT-ID> \
  -F client_secret=<AUTH-KEY>

L'output della richiesta include un token di autorizzazione (indicato da access-token nell'output riportato di seguito) che verrà passato successivamente con le chiamate API REST. Salvare questo token di autenticazione in un file di testo, che sarà necessario più avanti in questo articolo.

{"token_type":"Bearer","expires_in":"3599","expires_on":"1458245447","not_before":"1458241547","resource":"https://management.core.windows.net/","access_token":"<REDACTED>"}

Questo articolo usa l'approccio non interattivo . Per altre informazioni sull'autenticazione non interattiva (chiamate da servizio a servizio), vedere Chiamate da servizio a servizio tramite le credenziali.

Creare un account di Analisi Data Lake

È necessario creare un gruppo di risorse di Azure e un account Data Lake Store prima di poter creare un account Data Lake Analytics. Vedere Creare un account Data Lake Store.

Il comando Curl seguente illustra come creare un account:

curl -i -X PUT -H "Authorization: Bearer <REDACTED>" -H "Content-Type: application/json" https://management.azure.com/subscriptions/<AzureSubscriptionID>/resourceGroups/<AzureResourceGroupName>/providers/Microsoft.DataLakeAnalytics/accounts/<NewAzureDataLakeAnalyticsAccountName>?api-version=2016-11-01 -d@"C:\tutorials\adla\CreateDataLakeAnalyticsAccountRequest.json"

Sostituire <REDACTED> con il token di autorizzazione, <AzureSubscriptionID> con l'ID sottoscrizione, <AzureResourceGroupName> con il nome di un gruppo di risorse di Azure esistente e <NewAzureDataLakeAnalyticsAccountName> con il nome di un nuovo account Data Lake Analytics. Il payload della richiesta per questo comando è contenuto nel file CreateDatalakeAnalyticsAccountRequest.json specificato per il parametro -d precedente. Il contenuto del file input.json è simile al seguente:

{  
    "location": "East US 2",  
    "name": "myadla1004",  
    "tags": {},  
    "properties": {  
        "defaultDataLakeStoreAccount": "my1004store",  
        "dataLakeStoreAccounts": [  
            {  
                "name": "my1004store"  
            }     
        ]
    }  
}  

Elencare gli account di Data Lake Analytics in una sottoscrizione

Il comando Curl seguente illustra come elencare gli account in una sottoscrizione:

curl -i -X GET -H "Authorization: Bearer <REDACTED>" https://management.azure.com/subscriptions/<AzureSubscriptionID>/providers/Microsoft.DataLakeAnalytics/Accounts?api-version=2016-11-01

Sostituire <REDACTED> con il token di autorizzazione e <AzureSubscriptionID> con l'ID sottoscrizione. L'output è simile a:

{
    "value": [
        {
        "properties": {
            "provisioningState": "Succeeded",
            "state": "Active",
            "endpoint": "myadla0831.azuredatalakeanalytics.net",
            "accountId": "21e74660-0941-4880-ae72-b143c2615ea9",
            "creationTime": "2016-09-01T12:49:12.7451428Z",
            "lastModifiedTime": "2016-09-01T12:49:12.7451428Z"
        },
        "location": "East US 2",
        "tags": {},
        "id": "/subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/myadla0831rg/providers/Microsoft.DataLakeAnalytics/accounts/myadla0831",
        "name": "myadla0831",
        "type": "Microsoft.DataLakeAnalytics/accounts"
        },
        {
        "properties": {
            "provisioningState": "Succeeded",
            "state": "Active",
            "endpoint": "myadla1004.azuredatalakeanalytics.net",
            "accountId": "3ff9b93b-11c4-43c6-83cc-276292eeb350",
            "creationTime": "2016-10-04T20:46:42.287147Z",
            "lastModifiedTime": "2016-10-04T20:46:42.287147Z"
        },
        "location": "East US 2",
        "tags": {},
        "id": "/subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/myadla1004rg/providers/Microsoft.DataLakeAnalytics/accounts/myadla1004",
        "name": "myadla1004",
        "type": "Microsoft.DataLakeAnalytics/accounts"
        }
    ]
}

Ottenere informazioni su un account Data Lake Analytics account

Il comando Curl seguente illustra come ottenere informazioni su un account:

curl -i -X GET -H "Authorization: Bearer <REDACTED>" https://management.azure.com/subscriptions/<AzureSubscriptionID>/resourceGroups/<AzureResourceGroupName>/providers/Microsoft.DataLakeAnalytics/accounts/<DataLakeAnalyticsAccountName>?api-version=2015-11-01

Sostituire <REDACTED> con il token di autorizzazione, <AzureSubscriptionID> con l'ID sottoscrizione, <AzureResourceGroupName> con il nome di un gruppo di risorse di Azure esistente e <DataLakeAnalyticsAccountName> con il nome di un account Data Lake Analytics esistente. L'output è simile a:

{
    "properties": {
        "defaultDataLakeStoreAccount": "my1004store",
        "dataLakeStoreAccounts": [
        {
            "properties": {
            "suffix": "azuredatalakestore.net"
            },
            "name": "my1004store"
        }
        ],
        "provisioningState": "Creating",
        "state": null,
        "endpoint": null,
        "accountId": "3ff9b93b-11c4-43c6-83cc-276292eeb350",
        "creationTime": null,
        "lastModifiedTime": null
    },
    "location": "East US 2",
    "tags": {},
    "id": "/subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/myadla1004rg/providers/Microsoft.DataLakeAnalytics/accounts/myadla1004",
    "name": "myadla1004",
    "type": "Microsoft.DataLakeAnalytics/accounts"
}

Elencare gli archivi Data Lake di account Data Lake Analytics

Il comando Curl seguente illustra come elencare gli archivi Data Lake di un account:

curl -i -X GET -H "Authorization: Bearer <REDACTED>" https://management.azure.com/subscriptions/<AzureSubscriptionID>/resourceGroups/<AzureResourceGroupName>/providers/Microsoft.DataLakeAnalytics/accounts/<DataLakeAnalyticsAccountName>/DataLakeStoreAccounts/?api-version=2016-11-01

Sostituire <REDACTED> con il token di autorizzazione, <AzureSubscriptionID> con l'ID sottoscrizione, <AzureResourceGroupName> con il nome di un gruppo di risorse di Azure esistente e <DataLakeAnalyticsAccountName> con il nome di un account Data Lake Analytics esistente. L'output è simile a:

{
    "value": [
        {
        "properties": {
            "suffix": "azuredatalakestore.net"
        },
        "id": "/subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/myadla1004rg/providers/Microsoft.DataLakeAnalytics/accounts/myadla1004/dataLakeStoreAccounts/my1004store",
        "name": "my1004store",
        "type": "Microsoft.DataLakeAnalytics/accounts/dataLakeStoreAccounts"
        }
    ]
}

Inviare processi U-SQL

Il comando Curl seguente illustra come inviare un processo U-SQL:

curl -i -X PUT -H "Authorization: Bearer <REDACTED>" https://<DataLakeAnalyticsAccountName>.azuredatalakeanalytics.net/Jobs/<NewGUID>?api-version=2016-03-20-preview -d@"C:\tutorials\adla\SubmitADLAJob.json"

Sostituire <REDACTED> con il token di autorizzazione e <DataLakeAnalyticsAccountName> con il nome di un account Data Lake Analytics esistente. Il payload della richiesta per questo comando è contenuto nel file SubmitADLAJob.json fornito per il parametro -d indicato in precedenza. Il contenuto del file input.json è simile al seguente:

{
    "jobId": "8f8ebf8c-4b63-428a-ab46-a03d2cc5b65a",
    "name": "convertTSVtoCSV",
    "type": "USql",
    "degreeOfParallelism": 1,
    "priority": 1000,
    "properties": {
        "type": "USql",
        "script": "@searchlog =\n    EXTRACT UserId          int,\n            Start           DateTime,\n            Region          string,\n            Query          
    string,\n            Duration        int?,\n            Urls            string,\n            ClickedUrls     string\n    FROM \"/Samples/Data/SearchLog.tsv\"\n    US
    ING Extractors.Tsv();\n\nOUTPUT @searchlog   \n    TO \"/Output/SearchLog-from-Data-Lake.csv\"\nUSING Outputters.Csv();"
    }
}

L'output è simile a:

{
    "jobId": "8f8ebf8c-4b63-428a-ab46-a03d2cc5b65a",
    "name": "convertTSVtoCSV",
    "type": "USql",
    "submitter": "myadl@SPI",
    "degreeOfParallelism": 1,
    "priority": 1000,
    "submitTime": "2016-10-05T13:54:59.9871859+00:00",
    "state": "Compiling",
    "result": "Succeeded",
    "stateAuditRecords": [
        {
        "newState": "New",
        "timeStamp": "2016-10-05T13:54:59.9871859+00:00",
        "details": "userName:myadl@SPI;submitMachine:N/A"
        }
    ],
    "properties": {
        "owner": "myadl@SPI",
        "resources": [],
        "runtimeVersion": "default",
        "rootProcessNodeId": "00000000-0000-0000-0000-000000000000",
        "algebraFilePath": "adl://myadls0831.azuredatalakestore.net/system/jobservice/jobs/Usql/2016/10/05/13/54/8f8ebf8c-4b63-428a-ab46-a03d2cc5b65a/algebra.xml",
        "compileMode": "Semantic",
        "errorSource": "Unknown",
        "totalCompilationTime": "PT0S",
        "totalPausedTime": "PT0S",
        "totalQueuedTime": "PT0S",
        "totalRunningTime": "PT0S",
        "type": "USql"
    }
}

Elencare i processi U-SQL

Il comando Curl seguente illustra come elencare i processi U-SQL:

curl -i -X GET -H "Authorization: Bearer <REDACTED>" https://<DataLakeAnalyticsAccountName>.azuredatalakeanalytics.net/Jobs?api-version=2016-11-01 

Sostituire <REDACTED> con il token di autorizzazione e <DataLakeAnalyticsAccountName> con il nome di un account Data Lake Analytics esistente.

L'output è simile a:

{
"value": [
    {
    "jobId": "65cf1691-9dbe-43cd-90ed-1cafbfb406fb",
    "name": "convertTSVtoCSV",
    "type": "USql",
    "submitter": "someone@microsoft.com",
    "account": null,
    "degreeOfParallelism": 1,
    "priority": 1000,
    "submitTime": "Wed, 05 Oct 2016 13:46:53 GMT",
    "startTime": "Wed, 05 Oct 2016 13:47:33 GMT",
    "endTime": "Wed, 05 Oct 2016 13:48:07 GMT",
    "state": "Ended",
    "result": "Succeeded",
    "errorMessage": null,
    "storageAccounts": null,
    "stateAuditRecords": null,
    "logFilePatterns": null,
    "properties": null
    },
    {
    "jobId": "8f8ebf8c-4b63-428a-ab46-a03d2cc5b65a",
    "name": "convertTSVtoCSV",
    "type": "USql",
    "submitter": "someoneadl@SPI",
    "account": null,
    "degreeOfParallelism": 1,
    "priority": 1000,
    "submitTime": "Wed, 05 Oct 2016 13:54:59 GMT",
    "startTime": "Wed, 05 Oct 2016 13:55:43 GMT",
    "endTime": "Wed, 05 Oct 2016 13:56:11 GMT",
    "state": "Ended",
    "result": "Succeeded",
    "errorMessage": null,
    "storageAccounts": null,
    "stateAuditRecords": null,
    "logFilePatterns": null,
    "properties": null
    }
],
"nextLink": null,
"count": null
}

Ottenere gli elementi del catalogo

Il comando Curl seguente illustra come ottenere i database dal catalogo:

curl -i -X GET -H "Authorization: Bearer <REDACTED>" https://<DataLakeAnalyticsAccountName>.azuredatalakeanalytics.net/catalog/usql/databases?api-version=2016-11-01

L'output è simile a:

{
"@odata.context":"https://myadla0831.azuredatalakeanalytics.net/sqlip/$metadata#databases","value":[
    {
    "computeAccountName":"myadla0831","databaseName":"mytest","version":"f6956327-90b8-4648-ad8b-de3ff09274ea"
    },{
    "computeAccountName":"myadla0831","databaseName":"master","version":"e8bca908-cc73-41a3-9564-e9bcfaa21f4e"
    }
]
}

Vedere anche