Configuring an ADF Linked Service Connection for Square
For information on how to enable a connection for use with linked services, see Configuring a Linked Service Connection.
Field labels in this walkthrough follow the underlying Azure Data Factory property names, with the connection column that carries each value named alongside. The exact labels shown in the BimlFlex Connection Editor may differ.
After selecting Square from the Linked Service Type dropdown, the form required for creating a Square Linked Service will appear.
Source Only Connector
A Square connection is used as a source. It is not available as a target.
Objects of a Square connection are typed as Table or View.
The dataset addresses each object as a table, taking the table name from the TargetObjectName parameter.
Each Square object is copied whole. The copy passes the TargetSchemaName parameter and the source object name in the TargetObjectName parameter to the dataset, and BimlFlex composes no source query for the object.
The Square copy source takes no query. A filled Override SQL on a Square object, or the text of its Override SQL extension point, is not written to the copy, and the build reports a warning that names the object.
The object's Where SQL, Group By SQL and Order By SQL and the Append Source SQL extension point do not apply to a Square object.
Choosing an Authentication Method
| Method | Credentials | Additional Settings |
|---|---|---|
| Client Id, Client Secret and Tokens | Service Principal Id, Service Principal Key, Access Token and Refresh Token (optional) | redirectUri (optional) |
Recommendation: Store the Service Principal Key, the Access Token and the Refresh Token in Azure Key Vault rather than entering them as plaintext.
Complete Example: Client Id, Client Secret and Tokens with Azure Key Vault
| Field | Example Value |
|---|---|
| Connect via Integration Runtime | AutoResolveIntegrationRuntime |
| Host | contoso.mysquare.com |
| Redirect URI | https://contoso.com/square/callback |
| Service Principal Id | <client-id-of-square-application> |
| Azure Key Vault Linked Service | bfx-kv |
| Secret Name (for Service Principal Key) | BFX-LND-SquareClientSecret |
| Secret Name (for Access Token) | BFX-LND-SquareAccessToken |
| Secret Name (for Refresh Token) | BFX-LND-SquareRefreshToken |
Required Fields
Common Required Fields
A Square Linked Service connection uses a single Authentication Type, so the same fields are required on every connection.
These common required fields are:
- Connect via Integration Runtime
- Host
- Service Principal Id
- Service Principal Key (or Azure Key Vault)
- Access Token (or Azure Key Vault)
Connect via Integration Runtime
Connect via Integration Runtime names the integration runtime for a Square Linked Service connection.
The default value is AutoResolveIntegrationRuntime.
To use another runtime, select it from the dropdown or choose + New to add one.
When a custom value is saved in the linked service form, it will be added to the custom integration runtimes.
The custom values that appear in this dropdown can be maintained in Settings under Azure - AzureIntegrationRuntime.
Host
The Host identifies the Square instance the connector reads from (for example, contoso.mysquare.com).
It is stored in the connection's LS_Host column and maps to the ADF host property.
When the Host column is empty, the value is read from the connection's Additional Settings (LS_AdditionalSettings) under the key host.
Redirect URI
The Redirect URI is the redirect address assigned to the Square application in the Square application dashboard (for example, https://contoso.com/square/callback). It is optional.
The Redirect URI is stored in the connection's Additional Settings (LS_AdditionalSettings) under the key redirectUri, and maps to the ADF redirectUri property. When the key is empty, the property is not written.
In the BimlFlex Connection Editor, the Redirect URI is entered in the Redirect URI field on the ADF Linked Service tab.
Authentication Type
The Square Linked Service connection carries the client id and the client secret of the Square application, an access token and an optional refresh token. BimlFlex does not read the connection's Authentication Type column for this connector. BimlFlex has no interactive sign-in for Square. The client secret and the tokens are typed in or referenced from Azure Key Vault.
Client Id, Client Secret and Tokens
The Service Principal Id supplies the client id and is stored in the connection's LS_ServicePrincipalId column. It maps to the ADF clientId property.
In the BimlFlex Connection Editor, the client id is entered in the Client Id field on the ADF Linked Service tab.
The Service Principal Key supplies the client secret as plaintext in the LS_ServicePrincipalKey column, or as an Azure Key Vault reference held in the LS_ServicePrincipalKeyKVS_ fields that resolves to the secret at runtime. It maps to the ADF clientSecret property.
In the editor, the client secret is typed on the Client Secret tab, or the AKV Linked Service, Secret Name and optional Secret Version of the reference are entered on the Azure Key Vault tab beside it.
The Access Token is required. It is entered as plaintext in the LS_AccessToken column, or as an Azure Key Vault reference held in the LS_AccessTokenKVS_ fields that resolves to the token at runtime. It maps to the ADF accessToken property.
In the editor, the token is typed on the Access Token tab, or the AKV Linked Service, Secret Name and optional Secret Version of the reference are entered on the Azure Key Vault tab beside it.
The Refresh Token is optional. It is entered as plaintext in the LS_RefreshToken column, or as an Azure Key Vault reference held in the LS_RefreshTokenKVS_ fields that resolves to the token at runtime. It maps to the ADF refreshToken property. When neither form is filled, no refresh token is written.
In the editor, the token is typed on the Refresh Token tab, or the AKV Linked Service, Secret Name and optional Secret Version of the reference are entered on the Azure Key Vault tab beside it.
Square accepts a personal access token, which needs no refresh token, or an OAuth access token, which is used with its refresh token.
It is suggested that Azure Key Vault be used in place of manually entering the Service Principal Key, the Access Token and the Refresh Token.
Azure Data Factory Linked Service Additional Information
For additional information on ADF Square Linked Service and its connection requirements see the Azure Data Factory Square Connector documentation.