document

NAMESPACE

@@ -1,3 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+export(az_cognitive_service)
+export(call_cognitive_endpoint)
+export(cognitive_endpoint)
 import(AzureRMR)

R/az_cogsvc.R

@@ -1,3 +1,24 @@
+#' Azure Cognitive Service resource class
+#'
+#' Class representing a cognitive service resource, exposing methods for working with it.
+#'
+#' @docType class
+#' @section Methods:
+#' The following methods are available, in addition to those provided by the [AzureRMR::az_resource] class:
+#' - `list_keys()`: Return the access keys for this service.
+#' - `get_endpoint(key)`: Return the service endpoint, along with an access key. See 'Endpoints' below.
+#' - `regen_key(key)`: Regenerates (creates a new value for) an access key. The argument `key` can be 1 or 2.
+#' - `list_skus()`: List the SKUs (pricing tiers) available for this service.
+#'
+#' @section Initialization:
+#' Initializing a new object of this class can either retrieve an existing service, or create a new service on the host. Generally, the best way to initialize an object is via the `get_cognitive_service` and `create_cognitive_service` methods of the [az_resource_group] class, which handle the details automatically.
+#'
+#' @section Endpoints:
+#' The client-side interaction with a cognitive service is via an _endpoint_. Endpoint interaction in AzureCognitive is implemented using S3 classes. You can create a new endpoint object via the `get_endpoint()` method, or with the standalone `cognitive_endpoint()` function. If you use the latter, you will also have to supply any necessary authentication credentials, eg a shared key or token.
+#'
+#' @seealso
+#' [cognitive_endpoint], [create_cognitive_service], [get_cognitive_service]
+#' @export
 az_cognitive_service <- R6::R6Class("az_cognitive_service", inherit=AzureRMR::az_resource,
 
 public=list(
@@ -17,9 +38,9 @@ public=list(
         private$res_op("skus")$value
     },
 
-    get_endpoint=function()
+    get_endpoint=function(key=self$list_keys()[1])
     {
-        cognitive_endpoint(self$properties$endpoint, self$kind, key=self$list_keys()[1])
+        cognitive_endpoint(self$properties$endpoint, self$kind, key=key)
     }
 ))
 

R/endpoint.R

@@ -1,3 +1,26 @@
+#' Object representing an Azure Cognitive Service endpoint
+#'
+#' @param url The URL of the endpoint.
+#' @param type What type (or kind) of service the endpoint provides. See below for the services that AzureCognitive currently recognises.
+#' @param key The key to use to authenticate with the endpoint.
+#' @param aad_token. An Azure Active Directory (AAD) OAuth token, as an alternative to a key for the services that allow AAD authentication.
+#' @param cognitive_token A Cognitive Service token, as another alternative to a key for the services that accept it.
+#' @details
+#' Currently, `cognitive_endpoint` recognises the following types (or kinds) of services:
+#' - `ComputerVision`: generic computer vision service
+#' - `Face`: face recognition
+#' - `LUIS`: natural language understanding
+#' - `CustomVision.Training`: Training endpoint for a custom vision service
+#' - `CustomVision.Prediction`: Prediction endpoint for a custom vision service
+#' - `ContentModerator`: Content moderation (text and images)
+#' - `Text`: text analytics
+#'
+#' @return
+#' An object inheriting from class `cognitive_endpoint`, that can be used to communicate with the REST endpoint. The object will have a subclass based on the type of service provided.
+#'
+#' @seealso
+#' [call_cognitive_endpoint], [create_cognitive_service], [get_cognitive_service]
+#' @export
 cognitive_endpoint <- function(url, type, key=NULL, aad_token=NULL, cognitive_token=NULL)
 {
     type <- normalize_cognitive_type(type)
@@ -11,6 +34,25 @@ cognitive_endpoint <- function(url, type, key=NULL, aad_token=NULL, cognitive_to
 }
 
 
+#' Call a Cognitive Service REST endpoint
+#'
+#' @param endpoint An object of class `cognitive_endpoint`.
+#' @param operation The operation to perform.
+#' @param options Any query parameters that the operation takes.
+#' @param headers Any optional HTTP headers to include in the REST call. Note that `call_cognitive_endpoint` will handle authentication details automatically, so don't include them here.
+#' @param body The body of the HTTP request for the REST call.
+#' @param encode The encoding (really content-type) for the body. Can be `json` if the body is JSON text, or `raw` for a binary object.
+#' @param http_verb The HTTP verb for the REST call.
+#' @param http_status_handler How to handle a failed REST call. `stop`, `warn` and `message` will call the corresponding `*_for_status` handler in the httr package; `pass` will return the raw response object unchanged. The last one is mostly intended for debugging purposes.
+#' @details
+#' This function does the low-level work of constructing a HTTP request and then calling the REST endpoint. It is meant to be used by other packages that provide higher-level views of the service functionality.
+#'
+#' @return
+#' For a successful REST call, the contents of the response. This will usually be a list, obtained by translating the raw JSON body into R. If the call returns a non-success HTTP status code, based on the `http_status_handler` argument.
+#'
+#' @seealso
+#' [cognitive_endpoint], [create_cognitive_service], [get_cognitive_service]
+#' @export
 call_cognitive_endpoint <- function(endpoint, operation, options=list(), headers=list(), body=NULL, encode="json",
                                     http_verb=c("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"),
                                     http_status_handler=c("stop", "warn", "message", "pass"))
@@ -113,5 +155,5 @@ get_api_path <- function(type)
 
 normalize_cognitive_type <- function(type)
 {
-    tolower(gsub("\\.", "_", type))
+    tolower(gsub("[. ]", "_", type))
 }

man/az_cognitive_service.Rd

@@ -0,0 +1,38 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/az_cogsvc.R
+\docType{class}
+\name{az_cognitive_service}
+\alias{az_cognitive_service}
+\title{Azure Cognitive Service resource class}
+\format{An object of class \code{R6ClassGenerator} of length 24.}
+\usage{
+az_cognitive_service
+}
+\description{
+Class representing a cognitive service resource, exposing methods for working with it.
+}
+\section{Methods}{
+
+The following methods are available, in addition to those provided by the \link[AzureRMR:az_resource]{AzureRMR::az_resource} class:
+\itemize{
+\item \code{list_keys()}: Return the access keys for this service.
+\item \code{get_endpoint(key)}: Return the service endpoint, along with an access key. See 'Endpoints' below.
+\item \code{regen_key(key)}: Regenerates (creates a new value for) an access key. The argument \code{key} can be 1 or 2.
+\item \code{list_skus()}: List the SKUs (pricing tiers) available for this service.
+}
+}
+
+\section{Initialization}{
+
+Initializing a new object of this class can either retrieve an existing service, or create a new service on the host. Generally, the best way to initialize an object is via the \code{get_cognitive_service} and \code{create_cognitive_service} methods of the \link{az_resource_group} class, which handle the details automatically.
+}
+
+\section{Endpoints}{
+
+The client-side interaction with a cognitive service is via an \emph{endpoint}. Endpoint interaction in AzureCognitive is implemented using S3 classes. You can create a new endpoint object via the \code{get_endpoint()} method, or with the standalone \code{cognitive_endpoint()} function. If you use the latter, you will also have to supply any necessary authentication credentials, eg a shared key or token.
+}
+
+\seealso{
+\link{cognitive_endpoint}, \link{create_cognitive_service}, \link{get_cognitive_service}
+}
+\keyword{datasets}

man/call_cognitive_endpoint.Rd

@@ -0,0 +1,40 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/endpoint.R
+\name{call_cognitive_endpoint}
+\alias{call_cognitive_endpoint}
+\title{Call a Cognitive Service REST endpoint}
+\usage{
+call_cognitive_endpoint(endpoint, operation, options = list(),
+  headers = list(), body = NULL, encode = "json",
+  http_verb = c("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"),
+  http_status_handler = c("stop", "warn", "message", "pass"))
+}
+\arguments{
+\item{endpoint}{An object of class \code{cognitive_endpoint}.}
+
+\item{operation}{The operation to perform.}
+
+\item{options}{Any query parameters that the operation takes.}
+
+\item{headers}{Any optional HTTP headers to include in the REST call. Note that \code{call_cognitive_endpoint} will handle authentication details automatically, so don't include them here.}
+
+\item{body}{The body of the HTTP request for the REST call.}
+
+\item{encode}{The encoding (really content-type) for the body. Can be \code{json} if the body is JSON text, or \code{raw} for a binary object.}
+
+\item{http_verb}{The HTTP verb for the REST call.}
+
+\item{http_status_handler}{How to handle a failed REST call. \code{stop}, \code{warn} and \code{message} will call the corresponding \code{*_for_status} handler in the httr package; \code{pass} will return the raw response object unchanged. The last one is mostly intended for debugging purposes.}
+}
+\value{
+For a successful REST call, the contents of the response. This will usually be a list, obtained by translating the raw JSON body into R. If the call returns a non-success HTTP status code, based on the \code{http_status_handler} argument.
+}
+\description{
+Call a Cognitive Service REST endpoint
+}
+\details{
+This function does the low-level work of constructing a HTTP request and then calling the REST endpoint. It is meant to be used by other packages that provide higher-level views of the service functionality.
+}
+\seealso{
+\link{cognitive_endpoint}, \link{create_cognitive_service}, \link{get_cognitive_service}
+}

man/cognitive_endpoint.Rd

@@ -0,0 +1,41 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/endpoint.R
+\name{cognitive_endpoint}
+\alias{cognitive_endpoint}
+\title{Object representing an Azure Cognitive Service endpoint}
+\usage{
+cognitive_endpoint(url, type, key = NULL, aad_token = NULL,
+  cognitive_token = NULL)
+}
+\arguments{
+\item{url}{The URL of the endpoint.}
+
+\item{type}{What type (or kind) of service the endpoint provides. See below for the services that AzureCognitive currently recognises.}
+
+\item{key}{The key to use to authenticate with the endpoint.}
+
+\item{cognitive_token}{A Cognitive Service token, as another alternative to a key for the services that accept it.}
+
+\item{aad_token.}{An Azure Active Directory (AAD) OAuth token, as an alternative to a key for the services that allow AAD authentication.}
+}
+\value{
+An object inheriting from class \code{cognitive_endpoint}, that can be used to communicate with the REST endpoint. The object will have a subclass based on the type of service provided.
+}
+\description{
+Object representing an Azure Cognitive Service endpoint
+}
+\details{
+Currently, \code{cognitive_endpoint} recognises the following types (or kinds) of services:
+\itemize{
+\item \code{ComputerVision}: generic computer vision service
+\item \code{Face}: face recognition
+\item \code{LUIS}: natural language understanding
+\item \code{CustomVision.Training}: Training endpoint for a custom vision service
+\item \code{CustomVision.Prediction}: Prediction endpoint for a custom vision service
+\item \code{ContentModerator}: Content moderation (text and images)
+\item \code{Text}: text analytics
+}
+}
+\seealso{
+\link{call_cognitive_endpoint}, \link{create_cognitive_service}, \link{get_cognitive_service}
+}