Azure Cognitive Service resource class

Description

Class representing a cognitive service resource, exposing methods for working with it.

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(): 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_service_tiers(): List the service pricing tiers (SKUs) available for this service.

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 AzureRMR::az_resource_group class, which handle the details automatically.

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 subscription key or token.

See Also

cognitive_endpoint, create_cognitive_service, get_cognitive_service

Examples

## Not run: 

# recommended way of creating a new resource: via resource group method
rg <- AzureRMR::get_azure_login()$
    get_subscription("sub_id")$
    get_resource_group("rgname")
cogsvc <- rg$create_cognitive_service("myvisionservice",
    service_type="ComputerVision", service_tier="F0")

cogsvc$list_service_tiers()
cogsvc$list_keys()
cogsvc$regen_key()
cogsvc$get_endpoint()


## End(Not run)

Call a Cognitive Service REST endpoint

Description

Call a Cognitive Service REST endpoint

Usage

call_cognitive_endpoint(endpoint, ...)

## S3 method for class 'cognitive_endpoint'
call_cognitive_endpoint(endpoint, operation,
  options = list(), headers = list(), body = NULL, encode = NULL, ...,
  http_verb = c("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"),
  http_status_handler = c("stop", "warn", "message", "pass"))

Arguments

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.

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 http_status_handler argument.

See Also

cognitive_endpoint, create_cognitive_service, get_cognitive_service

Examples

## Not run: 

endp <- cognitive_endpoint("https://myvisionservice.api.cognitive.azure.com",
    service_type="Computervision", key="key")

# analyze an online image
img_link <- "https://news.microsoft.com/uploads/2014/09/billg1_print.jpg"
call_cognitive_endpoint(endp,
    operation="analyze",
    body=list(url=img_link),
    options=list(details="celebrities"),
    http_verb="POST")

# analyze an image on the local machine
img_raw <- readBin("image.jpg", "raw", file.info("image.jpg")$size)
call_cognitive_endpoint(endp,
    operation="analyze",
    body=img_raw,
    encode="raw",
    http_verb="POST")


## End(Not run)

Object representing an Azure Cognitive Service endpoint

Description

Object representing an Azure Cognitive Service endpoint

Usage

cognitive_endpoint(url, service_type, key = NULL, aad_token = NULL,
  cognitive_token = NULL, auth_header = "ocp-apim-subscription-key")

Arguments

Details

Currently, cognitive_endpoint recognises the following service types:

• CognitiveServices: multiple service types

• ComputerVision: generic computer vision service

• Face: face recognition

• LUIS: 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

• TextTranslate: text translation

Value

An object inheriting from class cognitive_endpoint, that can be used to communicate with the REST endpoint. The subclass of the object indicates the type of service provided.

See Also

call_cognitive_endpoint, create_cognitive_service, get_cognitive_service

Examples

## Not run: 

cognitive_endpoint("https://myvisionservice.api.cognitive.azure.com",
    service_type="Computervision", key="key")

cognitive_endpoint("https://mylangservice.api.cognitive.azure.com",
    service_type="LUIS", key="key")

# authenticating with AAD
token <- AzureAuth::get_azure_token("https://cognitiveservices.azure.com",
    tenant="mytenant", app="app_id", password="password")
cognitive_endpoint("https://myvisionservice.api.cognitive.azure.com",
    service_type="Computervision", aad_token=token)


## End(Not run)

Create, retrieve or delete an Azure Cognitive Service

Description

Methods for the AzureRMR::az_resource_group class.

Usage

create_cognitive_service(name, service_type, service_tier, location = self$location,
                         subdomain = name, properties = list(), ...)
get_cognitive_service(name)
delete_cognitive_service(name, confirm = TRUE, wait = FALSE)

Arguments

• name: The name for the cognitive service resource.

• service_type: The type of service (or "kind") to create. See 'Details' below.

• service_tier: The pricing tier (SKU) for the service.

• location: The Azure location in which to create the service. Defaults to the resource group's location.

• subdomain: The subdomain name to assign to the service; defaults to the resource name. Set this to NULL if you don't want to assign the service a subdomain of its own.

• properties: For create_cognitive_service, an optional named list of other properties for the service.

• confirm: For delete_cognitive_service, whether to prompt for confirmation before deleting the resource.

• wait: For delete_cognitive_service, whether to wait until the deletion is complete before returning.

Details

These are methods to create, get or delete a cognitive service resource within a resource group.

For create_cognitive_service, the type of service created can be one of the following:

• CognitiveServices: multiple service types

• ComputerVision: generic computer vision service

• Face: face recognition

• LUIS: 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

• TextTranslate: text translation

The possible tiers depend on the type of service created. Consult the Azure Cognitive Service documentation for more information. Usually there will be at least one free tier available.

Value

For create_cognitive_service and get_cognitive_service, an object of class az_cognitive_service.

See Also

cognitive_endpoint, call_cognitive_endpoint

Azure Cognitive Services documentation, REST API reference

Examples

## Not run: 

rg <- AzureRMR::get_azure_login()$
    get_subscription("sub_id")$
    get_resource_group("rgname")

rg$create_cognitive_service("myvisionservice",
    service_type="ComputerVision", service_tier="F0")

rg$create_cognitive_service("mylangservice",
    service_type="LUIS", service_tier="F0")

rg$get_cognitive_service("myvisionservice")

rg$delete_cognitive_service("myvisionservice")


## End(Not run)

Obtain authentication token for a cognitive service

Description

Obtain authentication token for a cognitive service

Usage

get_cognitive_token(key, region = "global", token_url = NULL)

Arguments