Analytics Links REST API

      +

      Overview

      The Analytics Links REST API is provided by the Analytics service. This API enables you to manage the links to remote Couchbase clusters and external data sources.

      The API schemes and host URLs are as follows:

      • http://node:8095/

      • https://node:18095/ (for secure access)

      where node is the host name or IP address of a node running the Analytics service.

      Version information

      Version : 7.1

      Tags

      • Single Links : Operations for single links.

      • Multiple Links : Operations for multiple links.

      • Legacy Methods : Operations provided for backward compatibility.

      Consumes

      • application/x-www-form-urlencoded

      Produces

      • application/json

      Resources

      This section describes the operations available with this REST API. The operations are grouped in the following categories.

      Operations for single links.

      POST /analytics/link/{scope}/{name}
      Description

      Creates a link in the specified Analytics scope.

      When creating or altering a remote link using an alternate address, note the following:

      • At least one node in the remote cluster must expose the mgmt port (rest_port, default 8091) or the mgmtSSL port (ssl_rest_port, default 18091).

      • Furthermore, all data nodes in the remote cluster must expose the kv port (memcached_port, default 11210) or the kvSSL port (memcached_ssl_port, default 11207).

      Failure to do so will result in a 400 (Bad Request) error.

      The SSL ports are required when the encryption mode is set to full; the non-SSL ports are required otherwise.
      When creating an external link, be sure to follow best practices for security. Root account credentials should never be used. It is recommended to grant the minimum possible permissions to perform the required operations, and only to allow access to the required data and resources.
      Parameters
      Type Name Description Schema

      Path

      scope
      required

      The name of the Analytics scope.

      With this parameter, the scope name may contain one or two identifiers, separated by a slash (/). You must URL-encode this parameter to escape any special characters.

      string

      Path

      name
      required

      The name of the link.

      string

      FormData

      type
      required

      The type of the link.

      couchbase: A link to a remote Couchbase cluster.
      s3: A link to the Amazon S3 service.
      azureblob: A link to Azure Blob Storage.

      enum (couchbase, s3, azureblob)

      FormData

      hostname
      required

      For Couchbase links only. The remote hostname.

      string

      FormData

      encryption
      required

      For Couchbase links only. The type of encryption used by the link.

      none: Neither passwords nor data are encrypted.
      half: Passwords are encrypted using SCRAM-SHA, but data is not.
      full: All data and passwords are encrypted and TLS is used.

      enum (none, half, full)

      FormData

      username
      optional

      For Couchbase links only. The remote username. Required for links with no encryption or half encryption. Required for links with full encryption if using a password.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      password
      optional

      For Couchbase links only. The remote password. Required for links with no encryption or half encryption. Required for links with full encryption if using a username.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      certificate
      optional

      For Couchbase links only. The content of the target cluster root certificate. Required for links with full encryption.

      You should URL-encode this parameter to escape any special characters. If required, this parameter may contain multiple certificates, separated by new lines.

      string

      FormData

      clientCertificate
      optional

      For Couchbase links, this is the content of the client certificate. Required for links with full encryption if using a client key.

      For Azure Blob links, this is the client certificate for the registered application. Used for Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientKey
      optional

      For Couchbase links only. The content of the client key. Required for links with full encryption if using a client certificate.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      accessKeyId
      required

      For S3 links only. The Amazon S3 access key ID.

      string

      FormData

      secretAccessKey
      required

      For S3 links only. The Amazon S3 secret access key.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      sessionToken
      optional

      For S3 links only. The Amazon S3 session token. Use this parameter if you want the link to have temporary access.

      Passing this parameter indicates that the accessKeyId and secretAccessKey are temporary credentials. The Amazon S3 service validates the session token with each request to check whether the provided credentials have expired or are still valid.

      string

      FormData

      region
      required

      For S3 links only. The Amazon S3 region.

      string

      FormData

      serviceEndpoint
      optional

      For S3 links only. The Amazon S3 service endpoint.

      string

      FormData

      endpoint
      required

      For Azure Blob links only. The endpoint URI.

      string

      FormData

      accountName
      optional

      For Azure Blob links only. The account name. Used for shared key authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      accountKey
      optional

      For Azure Blob links only. The account key. Used for shared key authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      sharedAccessSignature
      optional

      For Azure Blob links only. A token that can be used for authentication. Used for shared access signature authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      managedIdentityId
      optional

      For Azure Blob links only. The managed identity ID. Used for managed identity authentication. Only available if the application is running on an Azure instance, e.g. an Azure virtual machine.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientId
      optional

      For Azure Blob links only. The client ID for the registered application. Used for Azure Active Directory client secret authentication, or Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      tenantId
      optional

      For Azure Blob links only. The tenant ID where the registered application is created. Used for Azure Active Directory client secret authentication, or Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientSecret
      optional

      For Azure Blob links only. The client secret for the registered application. Used for Azure Active Directory client secret authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientCertificatePassword
      optional

      For Azure Blob links only. The client certificate password for the registered application. Used for Azure Active Directory client certificate authentication, if the client certificate is password-protected.

      You should URL-encode this parameter to escape any special characters.

      string

      Responses
      HTTP Code Description Schema

      200

      The operation was successful.

      No Content

      400

      Bad request. A parameter has an incorrect value.

      Errors

      500

      Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

      Errors

      Security
      Type Name

      basic

      Analytics Manage

      Example HTTP request

      The example below creates a Couchbase link named myCbLink in the Default scope, with no encryption.

      Curl request

      curl -v -u Administrator:password \
           -X POST \
           "http://localhost:8095/analytics/link/Default/myCbLink" \
           -d type=couchbase \
           -d hostname=remoteHostName:8091 \
           -d encryption=none \
           --data-urlencode username=remote.user \
           --data-urlencode password=remote.p4ssw0rd
      The username and password parameters are URL-encoded to escape any special characters.

      The example below creates a Microsoft Azure Blob link named myBlobLink in the Default scope, with anonymous authentication.

      Curl request

      curl -v -u Administrator:password \
           -X POST \
           "http://localhost:8095/analytics/link/Default/myBlobLink" \
           -d type=azureblob \
           -d endpoint=my.endpoint.uri

      The example below creates an Amazon S3 link named myAwsLink in the travel-sample.inventory scope.

      Curl request

      curl -v -u Administrator:password \
           -X POST \
           "http://localhost:8095/analytics/link/travel-sample%2Finventory/myAwsLink" \
           -d type=s3 \
           -d region=us-east-1 \
           -d accessKeyId=myAccessKey \
           --data-urlencode secretAccessKey=mySecretKey
      The dot separator within the scope name is converted to a slash (/), which is then URL-encoded as %2F. The secretAccessKey parameter is URL-encoded to escape any special characters.

      The example below creates an Amazon S3 link named myTempLink with temporary credentials in the travel-sample.inventory scope.

      Curl request

      curl -v -u Administrator:password \
           -X POST \
           "http://localhost:8095/analytics/link/travel-sample%2Finventory/myTempLink" \
           -d type=s3 \
           -d region=eu-west-1 \
           -d accessKeyId=myTempAccessKey \
           -d sessionToken=mySessionToken \
           --data-urlencode secretAccessKey=myTempSecretKey
      The dot separator within the scope name is converted to a slash (/), which is then URL-encoded as %2F. The secretAccessKey parameter is URL-encoded to escape any special characters.

      GET /analytics/link/{scope}/{name}
      Description

      Returns information about a link in the specified Analytics scope.

      Parameters
      Type Name Description Schema

      Path

      scope
      required

      The name of the Analytics scope.

      With this parameter, the scope name may contain one or two identifiers, separated by a slash (/). You must URL-encode this parameter to escape any special characters.

      string

      Path

      name
      required

      The name of the link.

      string

      Query

      type
      optional

      The type of the link. If this parameter is specified, the value must match the type that was set when the link was created.

      enum (couchbase, S3, azureblob)

      Responses
      HTTP Code Description Schema

      200

      Success. Returns an array of objects, each of which contains information about a link.

      < Links > array

      400

      Bad request. A parameter has an incorrect value.

      Errors

      500

      Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

      Errors

      Security
      Type Name

      basic

      Analytics Manage

      Example HTTP request

      The example below queries the myAwsLink link in the travel-sample.inventory scope.

      Curl request

      curl -v -u Administrator:password \
           "http://localhost:8095/analytics/link/travel-sample%2Finventory/myAwsLink"
      The dot separator within the scope name is converted to a slash (/), which is then URL-encoded as %2F.
      Example HTTP response

      Response 200

      [ {
        "accessKeyId" : "myAccessKey",
        "name" : "myAwsLink",
        "region" : "us-east-1",
        "scope" : "travel-sample/inventory",
        "secretAccessKey" : "<redacted sensitive entry>",
        "serviceEndpoint" : null,
        "type" : "s3"
      } ]

      PUT /analytics/link/{scope}/{name}
      Description

      Edits an existing link in the specified Analytics scope. The link name, type, and scope name cannot be modified.

      Parameters
      Type Name Description Schema

      Path

      scope
      required

      The name of the Analytics scope.

      With this parameter, the scope name may contain one or two identifiers, separated by a slash (/). You must URL-encode this parameter to escape any special characters.

      string

      Path

      name
      required

      The name of the link.

      string

      FormData

      type
      optional

      The type of the link. If this parameter is specified, the value must match the type that was set when the link was created.

      enum (couchbase, s3, azureblob)

      FormData

      hostname
      required

      For Couchbase links only. The remote hostname.

      string

      FormData

      encryption
      required

      For Couchbase links only. The type of encryption used by the link.

      none: Neither passwords nor data are encrypted.
      half: Passwords are encrypted using SCRAM-SHA, but data is not.
      full: All data and passwords are encrypted and TLS is used.

      enum (none, half, full)

      FormData

      username
      optional

      For Couchbase links only. The remote username. Required for links with no encryption or half encryption. Required for links with full encryption if using a password.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      password
      optional

      For Couchbase links only. The remote password. Required for links with no encryption or half encryption. Required for links with full encryption if using a username.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      certificate
      optional

      For Couchbase links only. The content of the target cluster root certificate. Required for links with full encryption.

      You should URL-encode this parameter to escape any special characters. If required, this parameter may contain multiple certificates, separated by new lines.

      string

      FormData

      clientCertificate
      optional

      For Couchbase links, this is the content of the client certificate. Required for links with full encryption if using a client key.

      For Azure Blob links, this is the client certificate for the registered application. Used for Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientKey
      optional

      For Couchbase links only. The content of the client key. Required for links with full encryption if using a client certificate.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      accessKeyId
      required

      For S3 links only. The Amazon S3 access key ID.

      string

      FormData

      secretAccessKey
      required

      For S3 links only. The Amazon S3 secret access key.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      sessionToken
      optional

      For S3 links only. The Amazon S3 session token. Use this parameter if you want the link to have temporary access.

      Passing this parameter indicates that the accessKeyId and secretAccessKey are temporary credentials. The Amazon S3 service validates the session token with each request to check whether the provided credentials have expired or are still valid.

      string

      FormData

      region
      required

      For S3 links only. The Amazon S3 region.

      string

      FormData

      serviceEndpoint
      optional

      For S3 links only. The Amazon S3 service endpoint.

      string

      FormData

      endpoint
      required

      For Azure Blob links only. The endpoint URI.

      string

      FormData

      accountName
      optional

      For Azure Blob links only. The account name. Used for shared key authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      accountKey
      optional

      For Azure Blob links only. The account key. Used for shared key authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      sharedAccessSignature
      optional

      For Azure Blob links only. A token that can be used for authentication. Used for shared access signature authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      managedIdentityId
      optional

      For Azure Blob links only. The managed identity ID. Used for managed identity authentication. Only available if the application is running on an Azure instance, e.g. an Azure virtual machine.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientId
      optional

      For Azure Blob links only. The client ID for the registered application. Used for Azure Active Directory client secret authentication, or Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      tenantId
      optional

      For Azure Blob links only. The tenant ID where the registered application is created. Used for Azure Active Directory client secret authentication, or Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientSecret
      optional

      For Azure Blob links only. The client secret for the registered application. Used for Azure Active Directory client secret authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientCertificatePassword
      optional

      For Azure Blob links only. The client certificate password for the registered application. Used for Azure Active Directory client certificate authentication, if the client certificate is password-protected.

      You should URL-encode this parameter to escape any special characters.

      string

      Responses
      HTTP Code Description Schema

      200

      The operation was successful.

      No Content

      400

      Bad request. A parameter has an incorrect value.

      Errors

      500

      Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

      Errors

      Security
      Type Name

      basic

      Analytics Manage

      Example HTTP request

      The example below edits the link named myCbLink in the Default scope to use full encryption with a client certificate and client key.

      Curl request

      curl -v -u Administrator:password \
           -X PUT \
           "http://localhost:8095/analytics/link/Default/myCbLink" \
           -d type=couchbase \
           -d hostname=remoteHostName:8091 \
           -d encryption=full \
           --data-urlencode "certificate=$(cat ./cert/targetClusterRootCert.pem)" \
           --data-urlencode "clientCertificate=$(cat ./cert/clientCert.pem)" \
           --data-urlencode "clientKey=$(cat ./cert/client.key)"
      The certificate, clientCertificate, and clientKey parameters use command substitution with the cat command to return the content of the referenced files. The content of these files is then URL-encoded to escape any special characters.

      DELETE /analytics/link/{scope}/{name}
      Description

      Deletes a link in the specified Analytics scope. The link cannot be deleted if any other entities are using it, such as an Analytics collection. The entities using the link need to be disconnected from the link, otherwise, the delete operation fails.

      Parameters
      Type Name Description Schema

      Path

      scope
      required

      The name of the Analytics scope.

      With this parameter, the scope name may contain one or two identifiers, separated by a slash (/). You must URL-encode this parameter to escape any special characters.

      string

      Path

      name
      required

      The name of the link.

      string

      Responses
      HTTP Code Description Schema

      200

      The operation was successful.

      No Content

      400

      Bad request. A parameter has an incorrect value.

      Errors

      500

      Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

      Errors

      Security
      Type Name

      basic

      Analytics Manage

      Example HTTP request

      The example below deletes the link named myCbLink from the Default scope.

      Curl request

      curl -v -u Administrator:password \
           -X DELETE \
           "http://localhost:8095/analytics/link/Default/myCbLink"

      The example below deletes the link named myAwsLink from the travel-sample.inventory scope.

      Curl request

      curl -v -u Administrator:password \
           -X DELETE \
           "http://localhost:8095/analytics/link/travel-sample%2Finventory/myAwsLink"
      The dot separator within the scope name is converted to a slash (/), which is then URL-encoded as %2F.

      Operations for multiple links.

      GET /analytics/link
      Description

      Returns information about all links in all Analytics scopes.

      Parameters
      Type Name Description Schema

      Query

      dataverse
      optional

      The name of an Analytics scope. When this parameter is included, the request only returns information about links in the specified scope.

      With this parameter, the scope name may only contain a single identifier.

      This parameter is provided for backward compatibility. Note that it is deprecated, and will be removed in a future release.

      string

      Query

      name
      optional

      The name of a link. When this parameter is included, the request only returns information about the specified link. If specified, the dataverse parameter must be specified also.

      This parameter is provided for backward compatibility. Note that it is deprecated, and will be removed in a future release.

      string

      Query

      type
      optional

      The type of the link. If this parameter is omitted, all link types are retrieved, excluding the Local link.

      enum (couchbase, s3, azureblob)

      Responses
      HTTP Code Description Schema

      200

      Success. Returns an array of objects, each of which contains information about a link.

      < Links > array

      400

      Bad request. A parameter has an incorrect value.

      Errors

      500

      Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

      Errors

      Security
      Type Name

      basic

      Analytics Manage

      Example HTTP request

      The example below queries all links of type S3 in all Analytics scopes.

      Curl request

      curl -v -u Administrator:password \
           "http://localhost:8095/analytics/link?type=S3"
      Example HTTP response

      Response 200

      [ {
        "accessKeyId" : "myAccessKey",
        "name" : "myAwsLink",
        "region" : "us-east-1",
        "scope" : "travel-sample/inventory",
        "secretAccessKey" : "<redacted sensitive entry>",
        "serviceEndpoint" : null,
        "type" : "s3"
      }, {
        "accessKeyId" : "myTempAccessKey",
        "name" : "myTempLink",
        "region" : "eu-west-1",
        "scope" : "travel-sample/inventory",
        "secretAccessKey" : "<redacted sensitive entry>",
        "serviceEndpoint" : null,
        "sessionToken" : "<redacted sensitive entry>",
        "type" : "s3"
      } ]

      GET /analytics/link/{scope}
      Description

      Returns information about all links in the specified Analytics scope.

      Parameters
      Type Name Description Schema

      Path

      scope
      required

      The name of the Analytics scope.

      With this parameter, the scope name may contain one or two identifiers, separated by a slash (/). You must URL-encode this parameter to escape any special characters.

      string

      Query

      type
      optional

      The type of the link. If this parameter is omitted, all link types are retrieved, excluding the Local link.

      enum (couchbase, s3, azureblob)

      Responses
      HTTP Code Description Schema

      200

      Success. Returns an array of objects, each of which contains information about a link.

      < Links > array

      400

      Bad request. A parameter has an incorrect value.

      Errors

      500

      Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

      Errors

      Security
      Type Name

      basic

      Analytics Manage

      Example HTTP request

      The example below queries all links in the Default scope.

      Curl request

      curl -v -u Administrator:password \
           "http://localhost:8095/analytics/link/Default"
      Example HTTP response

      Response 200

      [
        {
          "accountKey": null,
          "accountName": null,
          "clientCertificate": null,
          "clientCertificatePassword": null,
          "clientId": null,
          "clientSecret": null,
          "endpoint": "my.endpoint.uri",
          "managedIdentityId": null,
          "name": "myBlobLink",
          "scope": "Default",
          "sharedAccessSignature": null,
          "tenantId": null,
          "type": "azureblob"
        },
        {
          "activeHostname": "remoteHostName:8091",
          "bootstrapAlternateAddress": false,
          "bootstrapHostname": "remoteHostName:8091",
          "certificate": null,
          "clientCertificate": null,
          "clientKey": null,
          "clusterCompatibility": 393221,
          "encryption": "none",
          "name": "myCbLink",
          "nodes": [
            {
              "alternateAddresses": null,
              "hostname": null,
              "services": {
                "cbas": 8095,
                "cbasSSL": 18095,
                "kv": 11210,
                "kvSSL": 11207,
                "mgmt": 8091,
                "mgmtSSL": 18091
              }
            }
          ],
          "password": "<redacted sensitive entry>",
          "scope": "Default",
          "type": "couchbase",
          "username": "remote.user",
          "uuid": "6331e2a390125b662f7bcfd63ecb3a73"
        }
      ]

      Legacy Methods

      Operations provided for backward compatibility.

      POST /analytics/link

      Caution : This operation is deprecated, and will be removed in a future release.

      Description

      An alternative endpoint for creating a link, provided for backward compatibility.

      Parameters
      Type Name Description Schema

      FormData

      dataverse
      required

      The name of the Analytics scope containing the link.

      With this parameter, the scope name may only contain a single identifier.

      string

      FormData

      name
      required

      The name of the link.

      string

      FormData

      type
      required

      The type of the link.

      couchbase: A link to a remote Couchbase cluster.
      s3: A link to the Amazon S3 service.
      azureblob: A link to Azure Blob Storage.

      enum (couchbase, s3, azureblob)

      FormData

      hostname
      required

      For Couchbase links only. The remote hostname.

      string

      FormData

      encryption
      required

      For Couchbase links only. The type of encryption used by the link.

      none: Neither passwords nor data are encrypted.
      half: Passwords are encrypted using SCRAM-SHA, but data is not.
      full: All data and passwords are encrypted and TLS is used.

      enum (none, half, full)

      FormData

      username
      optional

      For Couchbase links only. The remote username. Required for links with no encryption or half encryption. Required for links with full encryption if using a password.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      password
      optional

      For Couchbase links only. The remote password. Required for links with no encryption or half encryption. Required for links with full encryption if using a username.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      certificate
      optional

      For Couchbase links only. The content of the target cluster root certificate. Required for links with full encryption.

      You should URL-encode this parameter to escape any special characters. If required, this parameter may contain multiple certificates, separated by new lines.

      string

      FormData

      clientCertificate
      optional

      For Couchbase links, this is the content of the client certificate. Required for links with full encryption if using a client key.

      For Azure Blob links, this is the client certificate for the registered application. Used for Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientKey
      optional

      For Couchbase links only. The content of the client key. Required for links with full encryption if using a client certificate.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      accessKeyId
      required

      For S3 links only. The Amazon S3 access key ID.

      string

      FormData

      secretAccessKey
      required

      For S3 links only. The Amazon S3 secret access key.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      sessionToken
      optional

      For S3 links only. The Amazon S3 session token. Use this parameter if you want the link to have temporary access.

      Passing this parameter indicates that the accessKeyId and secretAccessKey are temporary credentials. The Amazon S3 service validates the session token with each request to check whether the provided credentials have expired or are still valid.

      string

      FormData

      region
      required

      For S3 links only. The Amazon S3 region.

      string

      FormData

      serviceEndpoint
      optional

      For S3 links only. The Amazon S3 service endpoint.

      string

      FormData

      endpoint
      required

      For Azure Blob links only. The endpoint URI.

      string

      FormData

      accountName
      optional

      For Azure Blob links only. The account name. Used for shared key authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      accountKey
      optional

      For Azure Blob links only. The account key. Used for shared key authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      sharedAccessSignature
      optional

      For Azure Blob links only. A token that can be used for authentication. Used for shared access signature authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      managedIdentityId
      optional

      For Azure Blob links only. The managed identity ID. Used for managed identity authentication. Only available if the application is running on an Azure instance, e.g. an Azure virtual machine.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientId
      optional

      For Azure Blob links only. The client ID for the registered application. Used for Azure Active Directory client secret authentication, or Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      tenantId
      optional

      For Azure Blob links only. The tenant ID where the registered application is created. Used for Azure Active Directory client secret authentication, or Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientSecret
      optional

      For Azure Blob links only. The client secret for the registered application. Used for Azure Active Directory client secret authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientCertificatePassword
      optional

      For Azure Blob links only. The client certificate password for the registered application. Used for Azure Active Directory client certificate authentication, if the client certificate is password-protected.

      You should URL-encode this parameter to escape any special characters.

      string

      Responses
      HTTP Code Description Schema

      200

      The operation was successful.

      No Content

      400

      Bad request. A parameter has an incorrect value.

      Errors

      500

      Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

      Errors

      Security
      Type Name

      basic

      Analytics Manage

      PUT /analytics/link

      Caution : This operation is deprecated, and will be removed in a future release.

      Description

      An alternative endpoint for editing a link, provided for backward compatibility. The link name, type, and scope name cannot be modified.

      Parameters
      Type Name Description Schema

      FormData

      dataverse
      required

      The name of the Analytics scope containing the link.

      With this parameter, the scope name may only contain a single identifier.

      string

      FormData

      name
      required

      The name of the link.

      string

      FormData

      type
      optional

      The type of the link. If this parameter is specified, the value must match the type that was set when the link was created.

      enum (couchbase, s3, azureblob)

      FormData

      hostname
      required

      For Couchbase links only. The remote hostname.

      string

      FormData

      encryption
      required

      For Couchbase links only. The type of encryption used by the link.

      none: Neither passwords nor data are encrypted.
      half: Passwords are encrypted using SCRAM-SHA, but data is not.
      full: All data and passwords are encrypted and TLS is used.

      enum (none, half, full)

      FormData

      username
      optional

      For Couchbase links only. The remote username. Required for links with no encryption or half encryption. Required for links with full encryption if using a password.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      password
      optional

      For Couchbase links only. The remote password. Required for links with no encryption or half encryption. Required for links with full encryption if using a username.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      certificate
      optional

      For Couchbase links only. The content of the target cluster root certificate. Required for links with full encryption.

      You should URL-encode this parameter to escape any special characters. If required, this parameter may contain multiple certificates, separated by new lines.

      string

      FormData

      clientCertificate
      optional

      For Couchbase links, this is the content of the client certificate. Required for links with full encryption if using a client key.

      For Azure Blob links, this is the client certificate for the registered application. Used for Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientKey
      optional

      For Couchbase links only. The content of the client key. Required for links with full encryption if using a client certificate.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      accessKeyId
      required

      For S3 links only. The Amazon S3 access key ID.

      string

      FormData

      secretAccessKey
      required

      For S3 links only. The Amazon S3 secret access key.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      sessionToken
      optional

      For S3 links only. The Amazon S3 session token. Use this parameter if you want the link to have temporary access.

      Passing this parameter indicates that the accessKeyId and secretAccessKey are temporary credentials. The Amazon S3 service validates the session token with each request to check whether the provided credentials have expired or are still valid.

      string

      FormData

      region
      required

      For S3 links only. The Amazon S3 region.

      string

      FormData

      serviceEndpoint
      optional

      For S3 links only. The Amazon S3 service endpoint.

      string

      FormData

      endpoint
      required

      For Azure Blob links only. The endpoint URI.

      string

      FormData

      accountName
      optional

      For Azure Blob links only. The account name. Used for shared key authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      accountKey
      optional

      For Azure Blob links only. The account key. Used for shared key authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      sharedAccessSignature
      optional

      For Azure Blob links only. A token that can be used for authentication. Used for shared access signature authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      managedIdentityId
      optional

      For Azure Blob links only. The managed identity ID. Used for managed identity authentication. Only available if the application is running on an Azure instance, e.g. an Azure virtual machine.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientId
      optional

      For Azure Blob links only. The client ID for the registered application. Used for Azure Active Directory client secret authentication, or Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      tenantId
      optional

      For Azure Blob links only. The tenant ID where the registered application is created. Used for Azure Active Directory client secret authentication, or Azure Active Directory client certificate authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientSecret
      optional

      For Azure Blob links only. The client secret for the registered application. Used for Azure Active Directory client secret authentication.

      You should URL-encode this parameter to escape any special characters.

      string

      FormData

      clientCertificatePassword
      optional

      For Azure Blob links only. The client certificate password for the registered application. Used for Azure Active Directory client certificate authentication, if the client certificate is password-protected.

      You should URL-encode this parameter to escape any special characters.

      string

      Responses
      HTTP Code Description Schema

      200

      The operation was successful.

      No Content

      400

      Bad request. A parameter has an incorrect value.

      Errors

      500

      Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

      Errors

      Security
      Type Name

      basic

      Analytics Manage

      DELETE /analytics/link

      Caution : This operation is deprecated, and will be removed in a future release.

      Description

      An alternative endpoint for deleting a link, provided for backward compatibility. The link cannot be deleted if any other entities are using it, such as an Analytics collection. The entities using the link need to be disconnected from the link, otherwise, the delete operation fails.

      Parameters
      Type Name Description Schema

      FormData

      dataverse
      required

      The name of the Analytics scope containing the link.

      With this parameter, the scope name may only contain a single identifier.

      string

      FormData

      name
      required

      The name of the link.

      string

      Responses
      HTTP Code Description Schema

      200

      The operation was successful.

      No Content

      400

      Bad request. A parameter has an incorrect value.

      Errors

      500

      Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

      Errors

      Security
      Type Name

      basic

      Analytics Manage

      Definitions

      This section describes the properties returned by this REST API.

      These properties are common to all links.

      Name Description Schema

      scope
      required

      The name of the Analytics scope containing the link.

      The scope name may contain one or two identifiers, separated by a slash (/).
      Example : "travel-sample/inventory"

      string

      name
      required

      The name of the link.
      Example : "myLink"

      string

      type
      required

      The type of the link.

      couchbase: A link to a remote Couchbase cluster.
      s3: A link to the Amazon S3 service.
      azureblob: A link to Microsoft Azure Blob storage.

      Different properties are returned, depending on the link type: refer to Couchbase, S3, or Azure Blob.

      enum (couchbase, s3, azureblob)

      Couchbase

      These properties are returned for remote Couchbase links.

      Polymorphism : Inheritance
      Discriminator : type

      Name Description Schema

      scope
      required

      The name of the Analytics scope containing the link.

      The scope name may contain one or two identifiers, separated by a slash (/).
      Example : "travel-sample/inventory"

      string

      name
      required

      The name of the link.
      Example : "myLink"

      string

      type
      required

      The type of the link.

      couchbase: A link to a remote Couchbase cluster.
      s3: A link to the Amazon S3 service.
      azureblob: A link to Microsoft Azure Blob storage.

      Different properties are returned, depending on the link type: refer to Couchbase, S3, or Azure Blob.

      enum (couchbase, s3, azureblob)

      activeHostname
      required

      The remote hostname.
      Example : "remoteHostName:8091"

      string

      bootstrapAlternateAddress
      required

      Specifies whether the provided (bootstrap) hostname is an alternative address.
      Example : false

      boolean

      bootstrapHostname
      required

      The provided (bootstrap) hostname.
      Example : "remoteHostName:8091"

      string

      certificate
      required

      The content of the target cluster root certificate. Only set for links with full encryption. If not set, this property returns null.

      string

      clientCertificate
      required

      The content of the client certificate. Only set for links with full encryption using client certificate and client key. If not set, this property returns null.

      string

      clientKey
      required

      The content of the client key. Only set for links with full encryption using client certificate and client key. If not set, this property returns null.

      string

      clusterCompatibility
      required

      For internal use only.
      Example : 393221

      integer

      encryption
      required

      The type of encryption used by the link.

      none: Neither passwords nor data are encrypted.
      half: Passwords are encrypted using SCRAM-SHA, but data is not.
      full: All data and passwords are encrypted and TLS is used.

      enum (none, half, full)

      nodes
      required

      An array of objects, each of which contains information about a node in the target cluster.

      < Nodes > array

      password
      required

      The password used to connect to the link. This is redacted for the sake of security. Not set for links with full encryption using client certificate and client key. If not set, this property returns null.
      Example : "<redacted sensitive entry>"

      string

      username
      required

      The remote username. Not set for links with full encryption using client certificate and client key. If not set, this property returns null.
      Example : "remote.user"

      string

      uuid
      required

      A UUID uniquely identifying the link.
      Example : "6331e2a390125b662f7bcfd63ecb3a73"

      string (UUID)

      Nodes

      Name Description Schema

      alternateAddresses
      optional

      The alternate address defined on the node, if any. If not defined, this property returns null.

      string

      hostname
      optional

      The hostname of the node. If not defined, this property returns null.

      string

      services
      optional

      An object giving information about the services and ports configured on this node.

      Services

      Services

      Name Description Schema

      cbas
      optional

      The port number for a connection to the Analytics service.
      Example : 8095

      integer

      cbasSSL
      optional

      The port number for an encrypted connection to the Analytics service.
      Example : 18095

      integer

      kv
      optional

      The port number for a connection to the Data service.
      Example : 11210

      integer

      kvSSL
      optional

      The port number for an encrypted connection to the Data service.
      Example : 11207

      integer

      mgmt
      optional

      The port number for a connection to the Cluster Manager service.
      Example : 8091

      integer

      mgmtSSL
      optional

      The port number for an encrypted connection to the Cluster Manager service.
      Example : 18091

      integer

      S3

      These properties are returned for S3 links.

      Polymorphism : Inheritance
      Discriminator : type

      Name Description Schema

      scope
      required

      The name of the Analytics scope containing the link.

      The scope name may contain one or two identifiers, separated by a slash (/).
      Example : "travel-sample/inventory"

      string

      name
      required

      The name of the link.
      Example : "myLink"

      string

      type
      required

      The type of the link.

      couchbase: A link to a remote Couchbase cluster.
      s3: A link to the Amazon S3 service.
      azureblob: A link to Microsoft Azure Blob storage.

      Different properties are returned, depending on the link type: refer to Couchbase, S3, or Azure Blob.

      enum (couchbase, s3, azureblob)

      accessKeyId
      required

      The Amazon S3 access key ID.
      Example : "myAccessKey"

      string

      region
      required

      The Amazon S3 region.
      Example : "us-east-1"

      string

      secretAccessKey
      required

      The Amazon S3 secret access key. This is redacted for the sake of security.
      Example : "<redacted sensitive entry>"

      string

      sessionToken
      optional

      For S3 links only. The Amazon S3 session token. Indicates that the link has temporary access, and that the accessKeyId and secretAccessKey are temporary credentials. This is redacted for the sake of security.
      Example : "<redacted sensitive entry>"

      string

      serviceEndpoint
      required

      Amazon S3 service endpoint. If not set, this property returns null.
      Example : "my.endpoint.uri"

      string

      Azure Blob

      These properties are returned for Azure Blob links.

      Polymorphism : Inheritance
      Discriminator : type

      Name Description Schema

      scope
      required

      The name of the Analytics scope containing the link.

      The scope name may contain one or two identifiers, separated by a slash (/).
      Example : "travel-sample/inventory"

      string

      name
      required

      The name of the link.
      Example : "myLink"

      string

      type
      required

      The type of the link.

      couchbase: A link to a remote Couchbase cluster.
      s3: A link to the Amazon S3 service.
      azureblob: A link to Microsoft Azure Blob storage.

      Different properties are returned, depending on the link type: refer to Couchbase, S3, or Azure Blob.

      enum (couchbase, s3, azureblob)

      accountKey
      optional

      The account key. Used for shared key authentication. This is redacted for the sake of security. If not set, this property returns null.
      Example : "<redacted sensitive entry>"

      string

      accountName
      optional

      The account name. Used for shared key authentication. If not set, this property returns null.
      Example : "myAccountName"

      string

      clientCertificate
      optional

      The client certificate for the registered application. Used for Azure Active Directory client certificate authentication. This is redacted for the sake of security. If not set, this property returns null.
      Example : "<redacted sensitive entry>"

      string

      clientCertificatePassword
      optional

      The client certificate password for the registered application. Used for Azure Active Directory client certificate authentication, if the client certificate is password-protected. This is redacted for the sake of security. If not set, this property returns null.
      Example : "<redacted sensitive entry>"

      string

      clientId
      optional

      The client ID for the registered application. Used for Azure Active Directory client secret authentication, or Azure Active Directory client certificate authentication. If not set, this property returns null.
      Example : "myClientID"

      string

      clientSecret
      optional

      The client secret for the registered application. Used for Azure Active Directory client secret authentication. This is redacted for the sake of security. If not set, this property returns null.
      Example : "<redacted sensitive entry>"

      string

      endpoint
      required

      The endpoint URI.
      Example : "my.endpoint.uri"

      string

      managedIdentityId
      optional

      The managed identity ID. Used for managed identity authentication. If not set, this property returns null.
      Example : "myManagedIdentityID"

      string

      sharedAccessSignature
      optional

      A token that can be used for authentication. Used for shared access signature authentication. This is redacted for the sake of security. If not set, this property returns null.
      Example : "<redacted sensitive entry>"

      string

      tenantId
      optional

      The tenant ID where the registered application is created. Used for Azure Active Directory client secret authentication, or Azure Active Directory client certificate authentication. If not set, this property returns null.
      Example : "myTenantID"

      string

      Errors

      Name Description Schema

      error
      required

      An error message.

      string

      Security

      Analytics Manage

      The Analytics Links REST API supports HTTP basic authentication. Credentials can be passed via HTTP headers.

      Users must have one of the following RBAC roles:

      • Full Admin

      • Cluster Admin

      • Analytics Admin

      Refer to Roles for more details.

      Type : basic