---
title: "Introduction to AzureCognitive"
author: Hong Ooi
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{utf8}
---

AzureCognitive is a package for working with [Azure Cognitive Services](https://azure.microsoft.com/en-us/services/cognitive-services/). Both a Resource Manager interface and a client interface to the Cognitive Services REST API are provided. The aim is to provide a foundation that can be built on by other packages that will support specific services (Computer Vision, LUIS, etc).

## Resource Manager interface

AzureCognitive extends the class framework provided by [AzureRMR](https://github.com/Azure/AzureRMR) to support Cognitive Services. You can create, retrieve, update, and delete cognitive service resources by calling the corresponding methods for a resource group.

```r
az <- AzureRMR::get_azure_login()
sub <- az$get_subscription("sub_id")
rg <- sub$get_resource_group("rgname")

# create a new Computer Vision service
rg$create_cognitive_service("myvisionservice",
    service_type="ComputerVision", service_tier="S1")

# retrieve it
cogsvc <- rg$get_cognitive_service("myvisionservice")

# list subscription keys
cogsvc$list_keys()
```

## Client interface

AzureCognitive implements basic functionality for communicating with the Cognitive Services REST API. The main functions are `cognitive_endpoint`, which creates an object representing the endpoint, and `call_cognitive_endpoint` to perform the REST calls.

```r
# getting the endpoint from the resource object
endp <- cogsvc$get_endpoint()

# or standalone (must provide subscription key or other means of authentication)
endp <- cognitive_endpoint("https://myvisionservice.cognitiveservices.azure.com/",
    service_type="ComputerVision", key="key")

# analyze an 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")
```

The latter call produces output like that below (truncated for brevity).

```
$categories
$categories[[1]]
$categories[[1]]$name
[1] "people_"

$categories[[1]]$score
[1] 0.953125

$categories[[1]]$detail
$categories[[1]]$detail$celebrities
$categories[[1]]$detail$celebrities[[1]]
$categories[[1]]$detail$celebrities[[1]]$name
[1] "Bill Gates"

$categories[[1]]$detail$celebrities[[1]]$confidence
[1] 0.9999552
```