cosmos_endpoint {AzureCosmosR} | R Documentation |
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 |
key |
For |
key_type |
For |
api_version |
For |
endpoint |
For |
path |
For |
resource_type |
For |
resource_link |
For |
options |
For |
headers |
For |
body |
For |
encode |
For |
do_continuations |
For |
http_verb |
For |
num_retries |
For |
... |
Arguments passed to lower-level functions. |
response |
For |
http_status_handler |
For |
return_headers |
For |
simplify |
For |
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)