cosmos_endpoint() R function from [AzureCosmosR]

Client endpoint for Azure Cosmos DB core API


cosmos_endpoint(
  host,
  key,
  key_type = c("master", "resource"),
  api_version = getOption("azure_cosmosdb_api_version")
)

call_cosmos_endpoint(
  endpoint,
  path,
  resource_type,
  resource_link,
  options = list(),
  headers = list(),
  body = NULL,
  encode = "json",
  do_continuations = TRUE,
  http_verb = c("GET", "DELETE", "PUT", "POST", "PATCH", "HEAD"),
  num_retries = 10,
  ...
)

process_cosmos_response(response, ...)

## S3 method for class 'response'
process_cosmos_response(
  response,
  http_status_handler = c("stop", "warn", "message", "pass"),
  return_headers = NULL,
  simplify = FALSE,
  ...
)

## S3 method for class 'list'
process_cosmos_response(
  response,
  http_status_handler = c("stop", "warn", "message", "pass"),
  return_headers = NULL,
  simplify = FALSE,
  ...
)

Arguments

host: For cosmos_endpoint, the host URL for the endpoint. Typically of the form https://{account-name}.documents.azure.com:443/ (note the port number).
key: For cosmos_endpoint, a string containing the password for the endpoint. This can be either a master key or a resource token.
key_type: For cosmos_endpoint, the type of the key, either "master" or "resource".
api_version: For cosmos_endpoint, the API version to use.
endpoint: For call_cosmos_endpoint, a Cosmos DB endpoint object, as returned by cosmos_endpoint.
path: For call_cosmos_endpoint, the path in the URL for the endpoint call.
resource_type: For call_cosmos_endpoint, the type of resource: for example, "dbs" for a database, "colls" for a collection (container), "docs" for a document, etc.
resource_link: For call_cosmos_endpoint, a string to pass to the API for authorization purposes. See the Cosmos DB API documentation for more information.
options: For call_cosmos_endpoint, query options to include in the request URL.
headers: For call_cosmos_endpoint, any HTTP headers to include in the request. You don't need to include authorization headers as call_cosmos_endpoint will take care of the details.
body: For call_cosmos_endpoint, the body of the request if any.
encode: For call_cosmos_endpoint, the encoding (really content-type) of the request body. The Cosmos DB REST API uses JSON, so there should rarely be a need to change this argument.
do_continuations: For call_cosmos_endpoint, whether to automatically handle paged responses. If FALSE, only the initial response is returned.
http_verb: For call_cosmos_endpoint, the HTTP verb for the request. One of "GET", "POST", "PUT", "PATCH", "HEAD" or "DELETE".
num_retries: For call_cosmos_endpoint, how many times to retry a failed request. Useful for dealing with rate limiting issues.
...: Arguments passed to lower-level functions.
response: For process_cosmos_response, the returned object from a call_cosmos_endpoint call. This will be either a single httr request object, or a list of such objects.
http_status_handler: For process_cosmos_response, the R handler for the HTTP status code of the response. "stop", "warn" or "message" will call the corresponding handlers in httr, while "pass" ignores the status code. The latter is primarily useful for debugging purposes.
return_headers: For process_cosmos_response, whether to return the headers from the response object(s), as opposed to the body. Defaults to TRUE if the original endpoint call was a HEAD request, and FALSE otherwise.
simplify: For process_cosmos_response, whether to convert arrays of objects into data frames via the simplifyDataFrame argument to jsonlite::fromJSON .

Returns

For cosmos_endpoint, an object of S3 class cosmos_endpoint.

For call_cosmos_endpoint, either a httr response object, or a list of such responses (if a paged query, and do_continuations is TRUE).

For process_cosmos_response and a single response object, the content of the response. This can be either the parsed response body (if return_headers is FALSE) or the headers (if return_headers is TRUE).

For process_cosmos_response and a list of response objects, a list containing the individual contents of each response.

Details

These functions are the basis of the SQL API client framework provided by AzureCosmosR. The cosmos_endpoint function returns a client object, which can then be passed to other functions for querying databases and containers. The call_cosmos_endpoint function sends calls to the REST endpoint, the results of which are then processed by process_cosmos_response.

In most cases, you should not have to use call_cosmos_endpoint directly. Instead, use do_cosmos_op which provides a slightly higher-level interface to the API, by providing sensible defaults for the resource_type andresource_link arguments and partially filling in the request path.

As an alternative to AzureCosmosR, you can also use the ODBC protocol to interface with the SQL API. By installing a suitable ODBC driver, you can then talk to Cosmos DB in a manner similar to other SQL databases. An advantage of the ODBC interface is that it fully supports cross-partition queries, unlike the REST API. A disadvantage is that it does not support nested document fields; functions like array_contains() cannot be used, and attempts to reference arrays and objects may return incorrect results.

Note that AzureCosmosR is a framework for communicating directly with the core Cosmos DB client API, also known as the "SQL" API. Cosmos DB provides other APIs as options when creating an account, such as Cassandra, MongoDB, table storage and Gremlin. These APIs are not supported by AzureCosmosR, but you can use other R packages for working with them. For example, you can use AzureTableStor to work with the table storage API, or mongolite to work with the MongoDB API.

Examples


## Not run:

endp <- cosmos_endpoint("https://myaccount.documents.azure.com:443/", key="mykey")

# properties for the Cosmos DB account
call_cosmos_endpoint(endp, "", "", "") %>%
    process_cosmos_response()
## End(Not run)

cosmos_endpoint function

Client endpoint for Azure Cosmos DB core API

Arguments

Returns

Details

Examples

See Also