Linked service version 1 (V1)

Article
02/24/2022

Note

This reference documentation applies to Azure Data Factory version 1 (V1).

Create or Update

Creates a new linked service, or updates the content of an existing linked service.

Request

The Create or Update Linked Service request may be constructed as follows (HTTPS is recommended):

HTTP Verb	Request URI	HTTP Version
PUT	https://management.azure.com/subscriptions/{SubscriptionID}/resourcegroups/{ResourceGroupName}/providers/Microsoft.DataFactory/datafactories/{DataFactoryName}/linkedservices/{LinkedServiceName}?api-version={api-version}	HTTP/1.1

URI Parameters

URI Parameter	Required	Description
SubscriptionID	Yes	Your Azure subscription ID.
ResourceGroupName	Yes	A unique name for the resource group that hosts your Azure data factory Service.
DataFactoryName	Yes	Name for the data factory that you want to create your linked service in.
LinkedServiceName	Yes	Name of Linked Service you want to create.
Api-Version	Yes	Specifies the version of the protocol used to make this request.

Request Headers

The following table describes the request headers.

Request Header	Required	Description
x-ms-client-request-id	Yes	The operation ID for this request.

Request Body

The request body depends on your linked service type. The example here uses an Azure storage linked service.

The format of the request body is as follows:

  
Body:  
{  
    "name": <name>,  
    "properties": {  
        "type": <linkedservicetype>,  
        "typeProperties": {  
            "type specific property": "<value>",  
            "type specific property 2": "<value>"  
         }  
    }  
}

The following table describes the elements of the request body.

Element Name	Required	Description
name	Yes	Name of the linked service.
type	Yes	Type of the linked service.
typeProperties	Yes	Specify information needed to connect to the data store or compute service that you want to link to the data factory. The properties in this section vary based on the type of the data store/compute. Click on a data store in the "Supported data stores" section in Data Movement Activities article and Compute Linked Services for details.

Response

The response includes an HTTP status code, a set of response headers, and a response body.

Status Code

200 (OK) - if request was completed successfully.
202 (Accepted) - if request was accepted.
400 (Bad Request) - if request body fails validation.
404 (NotFound) - if subscription or resource group does not exist.
412 (Precondition Failed) - if condition specified by If-Match header failed.
501 (Not Implemented) - if validate is not implemented

Response Headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response Header	Description
x-ms-request-id	A unique identifier for the current operation, service generated.
x-ms-ratelimit-remaining-subscription-writes	The remaining limit for current subscription.
x-ms-correlation-request-id	Specifies the tracing correlation Id for the request; the resource provider must log this so that end-to-end requests can be correlated across Azure.
x-ms-routing-request-id	Location+DateTime+correlation-request-ID
Date	A UTC date/time value generated by the service that indicates the time at which the response was initiated.
Location	URI of the object you want to create or get.

Response Body

  
{  
    "id": ”subscriptions/{SubscriptionID>/resourcegroups/{ResourceGroupName>/providers/Microsoft.DataFactory/datafactories/{DataFactoryName>/linkedservices/{LinkedServiceName>”,  
    "name": <name>,  
    "properties": {  
        "hubName": <hubname>,  
        "type": "<type of linked service>",  
        "typeProperties": {  
            "type specific property": "<value>",  
            "type specific property 2": "<value>"  
        }  
        "provisioningState": <ProvisioningState>  
    }  
}

The following table describes the elements of the response body.

Element Name	Description
name	Name of the linked service.
ID	Specifies the identifying URL of the linked service.
type	Type of the linked service property.
typeProperties	Properties in this section vary based on the type of the data store/compute. Click on a data store in the "Supported data stores" section in Data Movement Activities article and Compute Linked Services for details.
hubname	The hub which contains your linked service.
provisionstate	Specifies the current provisioning state of the linked service. When a linked service is successfully created, the value of the element is Succeeded.

Sample Request and Response

Example URI:

  
PUT: https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/adf/providers/Microsoft.DataFactory/datafactories/test/linkedservices/linkedservicetest?api-version=2015-10-01

The request is sent with the following headers:

x-ms-client-request-id        : 00000000-1111-1111-1111-000000000000

and with the following body:

  
{  
    "name": "linkedservicetest ",  
    "properties": {  
    "type": "AzureStorage",  
    "typeProperties": {  
         "connectionString": "DefaultEndpointsProtocol=https;AccountName=myazurestorage;AccountKey=**********"  
    }  
}

After the request has been sent, the following response is returned.

  
Status Code:  
OK  
  
Headers:  
Pragma                        : no-cache  
x-ms-request-id               : 00000000-1111-1111-1111-000000000000  
x-ms-ratelimit-remaining-subscription-writes: 11999  
x-ms-correlation-request-id   : 00000000-1111-2222-1111-000000000000  
x-ms-routing-request-id       : WESTUS:20141203T213044Z: 00000000-1111-2222-1111-000000000000  
Strict-Transport-Security     : max-age=31536000; includeSubDomains  
Cache-Control                 : no-cache  
Date                          : Wed, 03 Dec 2014 21:30:44 GMT  
Server                        : Microsoft-IIS/8.5  
X-Powered-By                  : ASP.NET  
client-tracking-id            : 15

The response includes the following XML body:

  
{  
    "id": “subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/adf/providers/Microsoft.DataFactory/datafactories/test/linkedservices/linkedservicetest”,  
    "name": "LinkedServicetest",  
    "properties": {  
        "connectionString": "connectionString": "DefaultEndpointsProtocol=https;AccountName=testaccount;AccountKey=00000000000000000000000000000000000000000000000000000000000000000000000000000000000000==",  
        "hubName": "test_hub",  
        "type": "AzureStorage",  
        "typeProperties": {  
              "connectionString": "DefaultEndpointsProtocol=https;AccountName=myazurestorage;AccountKey=**********"  
         },  
        "id": "79346ee5-529d-4cba-9ca2-fb390b3e80c6",  
        "provisioningState": "Succeeded"  
    }  
}

Delete

Deletes the specific linked service.

Request

The Delete Linked Service request may be constructed as follows (HTTPS is recommended):

HTTP Verb	Request URI	HTTP Version
DELETE	https://management.azure.com/subscriptions/{SubscriptionID}/resourcegroups/{ResourceGroupName}/providers/Microsoft.DataFactory/datafactories/{DataFactoryName}/linkedservices/{LinkedServiceName}?api-version={api-version}	HTTP/1.1

URI Parameters

URI Parameter	Required	Description
SubscriptionID	Yes	Your Azure subscription ID.
ResourceGroupName	Yes	A unique name for the resource group that hosts your Azure data factory Service.
DataFactoryName	Yes	Name for the data factory that you want to delete your linked service in.
LinkedServiceName	Yes	Name of Linked Service you want to delete.
Api-Version	Yes	Specifies the version of the protocol used to make this request.

Request Headers

The following table describes the request headers.

Request Header	Required	Description
x-ms-client-request-id	Yes	The operation id for this request.

Request Body

None.

Response

The response includes an HTTP status code, a set of response headers, and a response body.

Status Code

200 (OK) if request completed successfully.
400 (Bad Request) if request body fails validation.
404 (NotFound) if subscription or resource group does not exist.
412 (Precondition Failed) if failed condition specified by If-Match header.
501 (Not Implemented) if validate is not implemented

Response Headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response Header	Description
x-ms-request-id	A unique identifier for the current operation, service generated.
x-ms-ratelimit-remaining-subscription-writes	The remaining limit for current subscription.
x-ms-correlation-request-id	Specifies the tracing correlation Id for the request; the resource provider must log this so that end-to-end requests can be correlated across Azure.
x-ms-routing-request-id	Location+DateTime+correlation-request-ID
Date	A UTC date/time value generated by the service that indicates the time at which the response was initiated.

Response Body

None.

Sample Request and Response

Example URI:

DELETE: https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/adf/providers/Microsoft.DataFactory/datafactories/test/linkedservices/linkedservicetest?api-version=2015-10-01

The request is sent with the following headers.

  
x-ms-client-request-id        : 00000000-1111-1111-1111-000000000000

After the request has been sent, the following response is returned.

  
Status Code:  
OK  
  
Headers:  
Pragma                        : no-cache  
x-ms-request-id               : 00000000-1111-1111-1111-000000000000  
x-ms-ratelimit-remaining-subscription-writes: 11996  
x-ms-correlation-request-id   : 00000000-1111-2222-1111-000000000000  
x-ms-routing-request-id       : WESTUS:20141203T213044Z: 00000000-1111-2222-1111-000000000000  
Strict-Transport-Security     : max-age=31536000; includeSubDomains  
Cache-Control                 : no-cache  
Date                          : Wed, 03 Dec 2014 21:30:44 GMT  
Server                        : Microsoft-IIS/8.5  
X-Powered-By                  : ASP.NET  
client-tracking-id            : 93

Get

Gets information about the specified linked service.

Request

The Get Linked Service request may be constructed as follows (HTTPS is recommended):

HTTP Verb	Request URI	HTTP Version
GET	https://management.azure.com/subscriptions/{SubscriptionID}/resourcegroups/{ResourceGroupName}/providers/Microsoft.DataFactory/datafactories/{DataFactoryName}/linkedservices/{LinkedServiceName}?api-version={api-version}	HTTP/1.1

URI Parameters

URI Parameter	Required	Description
SubscriptionID	Yes	Your Azure subscription ID
ResourceGroupName	Yes	The unique name for the resource group that hosts your Azure data factory.
DataFactoryName	Yes	Name for the data factory that you want to find your linked service in.
LinkedServiceName	Yes	Name of the linked service that you want to find.
Api-Version	Yes	Specifies the version of the protocol used to make this request.

Request Headers

The following table describes the request headers.

Request Header	Required	Description
x-ms-client-request-id	Yes	The operation ID for this request.

Request Body

None.

Response

The response includes an HTTP status code, a set of response headers, and a response body.

Status Code

200 (OK) - if the request was completed successfully.
400 (Bad Request) if the request body fails validation.
404 (NotFound) if the subscription or resource group does not exist.
412 (Precondition Failed) - if the condition specified by the If-Match header failed.
501 (Not Implemented) - if validate is not implemented

Response Headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response Header	Description
x-ms-request-id	A unique identifier for the current operation, service generated.
x-ms-ratelimit-remaining-subscription-writes	The remaining limit for current subscription.
x-ms-correlation-request-id	Specifies the tracing correlation Id for the request; the resource provider must log this so that end-to-end requests can be correlated across Azure.
x-ms-routing-request-id	Location+DateTime+correlation-request-ID
Date	A UTC date/time value generated by the service that indicates the time at which the response was initiated.

Response Body

The response body depends on your linked service type, this example we are using Azure storage linked service, for more information about linked services, see Linked Services.

  
{  
    "id": ”subscriptions/{SubscriptionID>/resourcegroups/{ResourceGroupName>/providers/Microsoft.DataFactory/datafactories/{DataFactoryName>/linkedservices/{LinkedServiceName>”,  
    "name": <name>,  
    "properties": {  
        "hubName": <hubname>,  
        "type": "AzureStorage",  
        "typeConnectionString": {  
            "type specific property": "<value>",  
            "type specific property 2": "<value>"  
         }  
        "provisioningState": <ProvisioningState>  
    }  
}

The following table describes the elements of the response body.

Element Name	Description
name	Name of the linked service.
ID	Specifies the identifying URL of the Linked Service.
type	Type of the linked service property.
typeProperties	Properties in this section vary based on the type of the data store/compute. Click on a data store in the "Supported data stores" section in Data Movement Activities article and Compute Linked Services for details.
hubname	The hub which contains your linked service
provisionstate	Specifies the current provisioning state of the linked service. When a linked service is successfully created, the value of the element is Succeeded.

Sample Request and Response

Example URI:

  
GET: https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/adf/providers/Microsoft.DataFactory/datafactories/test/linkedservices/linkedservicetest?api-version=2015-10-01

The request is sent with the following headers.

x-ms-client-request-id        : 00000000-1111-1111-1111-000000000000

After the request has been sent, the following response is returned.

  
Status Code:  
OK  
  
Headers:  
Pragma                        : no-cache  
x-ms-request-id               : 00000000-1111-1111-1111-000000000000  
x-ms-ratelimit-remaining-subscription-writes: 11999  
x-ms-correlation-request-id   : 00000000-1111-2222-1111-000000000000  
x-ms-routing-request-id       : WESTUS:20141203T213044Z: 00000000-1111-2222-1111-000000000000  
Strict-Transport-Security     : max-age=31536000; includeSubDomains  
Cache-Control                 : no-cache  
Date                          : Wed, 03 Dec 2014 21:30:44 GMT  
Server                        : Microsoft-IIS/8.5  
X-Powered-By                  : ASP.NET  
The response includes the following XML body.  
{  
    "id": “subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/adf/providers/Microsoft.DataFactory/datafactories/test/linkedservices/linkedservicetest”,  
    "name": "LinkedServicetest ",  
    "properties": {  
        "hubName": "test_hub",  
        "type": "AzureStorage",  
        "typeProperties": {  
          "connectionString": "DefaultEndpointsProtocol=https;AccountName=myazurestorage;AccountKey=**********"  
        },  
        "id": "00000000-0000-0000-0000-000000000000",  
        "provisioningState": "Succeeded"  
    }  
}

List

Lists information of all linked services in the data factory.

Request

The List Linked Service request may be constructed as follows (HTTPS is recommended):

HTTP Verb	Request URI	HTTP Version
GET	https://management.azure.com/subscriptions/{SubscriptionID}/resourcegroups/{ResourceGroupName}/providers/Microsoft.DataFactory/datafactories/{DataFactoryName}/linkedservices?api-version={api-version}	HTTP/1.1

URI Parameters

URI Parameter	Required	Description
SubscriptionID	Yes	Your Azure subscription ID
ResourceGroupName	Yes	A unique name for the resource group that hosts your Azure data factory DataFactoryName.
DataFactoryName	Yes	Name for the data factory that you want to find your linked service.
Api-Version	Yes	Specifies the version of the protocol used to make this request.

Request Headers

The following table describes the request headers.

Request Header	Required	Description
x-ms-client-request-id	Yes	The operation id for this request.

Request Body

None.

Response

The response includes an HTTP status code, a set of response headers, and a response body.

Status Code

200 (OK) - if the request completed successfully.
400 (Bad Request) - if the request body fails validation.
404 (NotFound) - if the subscription or resource group does not exist.
412 (Precondition Failed) - if the condition specified by If-Match header failed.

Response Headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response Header	Description
x-ms-request-id	A unique identifier for the current operation, service generated.
x-ms-ratelimit-remaining-subscription-writes	The remaining limit for current subscription.
x-ms-correlation-request-id	Specifies the tracing correlation Id for the request. The resource provider must log this so that end-to-end requests can be correlated across Azure.
x-ms-routing-request-id	Location+DateTime+correlation-request-ID
Date	A UTC date/time value generated by the service that indicates the time at which the response was initiated.
Location	URI of the object you want to create or get.

Response Body

The structure of property depends on the type of linked service, for more information about linked services, see Linked Services.

  
{  
    "value": [  
    {  
        "id":         ”/subscriptions/{SubscriptionID>/resourcegroups/{ResourceGroupName>/providers/Microsoft.DataFactory/datafactories/{DataFactoryName>/linkedservices/{LinkedServiceName1>”,  
        "name": <name1>,  
        "properties": {  
            "hubName": <hubname>,  
            "type": "AzureStorage",  
            "typeProperties": {  
                "type specific property": "<value>",  
                "type specific property 2": "<value>"  
            }  
            "provisioningState": "Succeeded"  
        }  
    },  
    {  
        "id":         ”/subscriptions/{SubscriptionID>/resourcegroups/{ResourceGroupName>/providers/Microsoft.DataFactory/datafactories/{DataFactoryName>/linkedservices/{LinkedServiceName2>”,  
        "name": <name2>,  
        "properties": {  
            "hubName": <hubname>,  
            "type": "AzureSql",  
            "typeProperties": {  
                 "type specific property": "<value>",  
                 "type specific property 2": "<value>"  
             }  
            "provisioningState": "Succeeded"  
        }  
    }  
]  
}

The following table describes the elements of the response body.

Element Name	Description
name	Name of the linked service.
ID	Specifies the identifying URL of the linked service.
type	Type of the linked service property.
typeProperties	Properties in this section vary based on the type of the data store/compute. Click on a data store in the "Supported data stores" section in Data Movement Activities article and Compute Linked Services for details.
hubname	The hub which contains your linked service.
provisionstate	Specifies the current provisioning state of the linked service. When a linked service is successfully created, the value of the element is Succeeded.

If there are more than 100 records, you will get 100 records at a time with a nextLink:

{
    "value": [  
    {  
        "id":         ”/subscriptions/{SubscriptionID>/resourcegroups/{ResourceGroupName>/providers/Microsoft.DataFactory/datafactories/{DataFactoryName>/linkedservices/{LinkedServiceName1>”,  
        "name": <name1>,  
        "properties": {  
            "hubName": <hubname>,  
            "type": "AzureStorage",  
            "typeProperties": {  
                "type specific property": "<value>",  
                "type specific property 2": "<value>"  
            }  
            "provisioningState": "Succeeded"  
        }  
    },  
    {  
        "id":         ”/subscriptions/{SubscriptionID>/resourcegroups/{ResourceGroupName>/providers/Microsoft.DataFactory/datafactories/{DataFactoryName>/linkedservices/{LinkedServiceName2>”,  
        "name": <name2>,  
        "properties": {  
            "hubName": <hubname>,  
            "type": "AzureSql",  
            "typeProperties": {  
                 "type specific property": "<value>",  
                 "type specific property 2": "<value>"  
             }  
            "provisioningState": "Succeeded"  
        }  
    }  
    ],
    "nextLink": "https://management.azure.com/subscriptions/{subscription ID>/resourcegroups/{Resource group name>/providers/Microsoft.DataFactory/datafactories/{data factory name>/linkedservices?api-version=2015-10-01&%24skipToken=MSExNiFSR0YwWVVGeWRHbG1ZV04wCjEhNTIhUkVGZlpUSXlaR1UyTXpndFpURTJNeTAwWXpZNUxUaGhNR0l0Wm1VMU1ETmpOakF4T0RObA%3d%3d"
}

You send the next request using the nextLink URL to get the next set of records. You may need to wrap & with double quotes ("") in the nextLink URL. Only 100 records are returned at a time.

Sample Request and Response

Example URI:

  
GET: https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/adf/providers/Microsoft.DataFactory/datafactories/test/linkedservices?api-version=2015-10-01

The request is sent with the following headers.

x-ms-client-request-id        : 00000000-1111-1111-1111-000000000000

After the request has been sent, the following response is returned.

  
Status Code:  
OK  
  
Headers:  
Pragma                        : no-cache  
x-ms-request-id               : 00000000-1111-1111-1111-000000000000  
x-ms-ratelimit-remaining-subscription-writes: 799997  
x-ms-correlation-request-id   : 00000000-1111-2222-1111-000000000000  
x-ms-routing-request-id       : WESTUS:20141203T213044Z: 00000000-1111-2222-1111-000000000000  
Strict-Transport-Security     : max-age=31536000; includeSubDomains  
Cache-Control                 : no-cache  
Date                          : Wed, 03 Dec 2014 21:30:44 GMT  
Server                        : Microsoft-IIS/8.5  
X-Powered-By                  : ASP.NET

The response includes the following XML body.

  
{  
    "value": [  
    {  
        "id": “/subscriptions/00000000-0000-0000-0000-  000000000000/resourcegroups/adf/providers/Microsoft.DataFactory/datafactories  /test/linkedservices/linkedservicetest”,  
        "name": "LinkedServicetest",  
        "properties": {  
            "hubName": "test_hub",  
            "type": "AzureStorage",  
             "typeProperties": {  
                  "connectionString": "DefaultEndpointsProtocol=https;AccountName=myazurestorage;AccountKey=**********"  
             },  
            "provisioningState": "Succeeded"  
        }  
    },  
    {  
        "id": “/subscriptions/00000000-0000-0000-0000-  000000000000/resourcegroups/adf/providers/Microsoft.DataFactory/datafactories  /test/linkedservices/linkedservicetest2”,  
        "name": "LinkedServicetest2",  
        "properties": {  
            "hubName": "test_hub",  
            "type": "AzureSql",  
             "typeProperties": {  
                  "connectionString": "DefaultEndpointsProtocol=https;AccountName=myazurestorage2;AccountKey=**********"  
             },  
            "provisioningState": "Succeeded"  
        }  
    },

Linked service version 1 (V1)

Create or Update

Request

URI Parameters

Request Headers

Request Body

Response

Status Code

Response Headers

Response Body

Sample Request and Response

Delete

Request

URI Parameters

Request Headers

Request Body

Response

Status Code

Response Headers

Response Body

Sample Request and Response

Get

Request

URI Parameters

Request Headers

Request Body

Response

Status Code

Response Headers

Response Body

Sample Request and Response

List

Request

URI Parameters

Request Headers

Request Body

Response

Status Code

Response Headers

Response Body

Sample Request and Response

Additional resources