cosmos_endpoint {AzureCosmosR}

Client endpoint for Azure Cosmos DB core API

Description

Client endpoint for Azure Cosmos DB core API

Usage

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.

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.

Value

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.

See Also

do_cosmos_op, cosmos_database, cosmos_container, az_cosmosdb

httr::VERB, which is what carries out the low-level work of sending the HTTP request.

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)