Added sample 15.handling-attachments (#1047)

* Added sample 15.handling-attachments

* Corrected package name in 15.handling-attachments

Author: tracyboehrer

libraries/bot-connector/src/main/java/com/microsoft/bot/connector/Attachments.java

@@ -35,4 +35,21 @@ public interface Attachments {
      * @throws IllegalArgumentException thrown if parameters fail the validation
      */
     CompletableFuture<InputStream> getAttachment(String attachmentId, String viewId);
+
+    /**
+     * Get the URI of an attachment view.
+     * @param attachmentId id of the attachment.
+     * @param viewId default is "original".
+     * @return URI of the attachment.
+     */
+    String getAttachmentUri(String attachmentId, String viewId);
+
+    /**
+     * Get the URI of an attachment view.
+     * @param attachmentId id of the attachment.
+     * @return URI of the attachment.
+     */
+    default String getAttachmentUri(String attachmentId) {
+        return getAttachmentUri(attachmentId, "original");
+    }
 }

libraries/bot-connector/src/main/java/com/microsoft/bot/connector/rest/RestAttachments.java

@@ -7,6 +7,8 @@
 package com.microsoft.bot.connector.rest;
 
 import com.microsoft.bot.connector.Async;
+import java.net.URLEncoder;
+import org.apache.commons.lang3.StringUtils;
 import retrofit2.Retrofit;
 import com.microsoft.bot.connector.Attachments;
 import com.google.common.reflect.TypeToken;
@@ -165,4 +167,30 @@ private ServiceResponse<InputStream> getAttachmentDelegate(
             .registerError(ErrorResponseException.class)
             .build(response);
     }
+
+    /**
+     * Get the URI of an attachment view.
+     * @param attachmentId id of the attachment.
+     * @param viewId default is "original".
+     * @return URI of the attachment.
+     */
+    @Override
+    public String getAttachmentUri(String attachmentId, String viewId) {
+        if (StringUtils.isEmpty(attachmentId)) {
+            throw new IllegalArgumentException("Must provide an attachmentId");
+        }
+
+        if (StringUtils.isEmpty(viewId)) {
+            viewId = "original";
+        }
+
+        String baseUrl = client.baseUrl();
+        String uri = baseUrl
+            + (baseUrl.endsWith("/") ? "" : "/")
+            + "v3/attachments/{attachmentId}/views/{viewId}";
+        uri = uri.replace("{attachmentId}", URLEncoder.encode(attachmentId));
+        uri = uri.replace("{viewId}", URLEncoder.encode(viewId));
+
+        return uri;
+    }
 }

samples/15.handling-attachments/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

samples/15.handling-attachments/README.md

@@ -0,0 +1,97 @@
+# Handling Attachments
+
+Bot Framework v4 handling attachments bot sample
+
+This bot has been created using [Bot Framework](https://dev.botframework.com), it shows how to send outgoing attachments and how to save attachments to disk.
+
+> **NOTE: A specific example for Microsoft Teams, demonstrating how to
+upload files to Teams from a bot and how to receive a file sent to a bot as an attachment, can be found [here](../56.teams-file-upload)**
+
+## Prerequisites
+
+- Java 1.8+
+- Install [Maven](https://maven.apache.org/)
+- An account on [Azure](https://azure.microsoft.com) if you want to deploy to Azure.
+
+## To try this sample locally
+- From the root of this project folder:
+  - Build the sample using `mvn package`
+  - Run it by using `java -jar .\target\bot-attachments-sample.jar`
+
+- Test the bot using Bot Framework Emulator
+
+  [Bot Framework Emulator](https://github.com/microsoft/botframework-emulator) is a desktop application that allows bot developers to test and debug their bots on localhost or running remotely through a tunnel.
+
+  - Install the Bot Framework Emulator version 4.3.0 or greater from [here](https://github.com/Microsoft/BotFramework-Emulator/releases)
+
+  - Connect to the bot using Bot Framework Emulator
+
+    - Launch Bot Framework Emulator
+    - File -> Open Bot
+    - Enter a Bot URL of `http://localhost:3978/api/messages`
+
+## Interacting with the bot
+
+A message exchange between user and bot may contain cards and media attachments, such as images, video, audio, and files.
+The types of attachments that may be sent and received varies by channel. Additionally, a bot may also receive file attachments.
+
+## Deploy the bot to Azure
+
+As described on [Deploy your bot](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-deploy-az-cli), you will perform the first 4 steps to setup the Azure app, then deploy the code using the azure-webapp Maven plugin.
+
+### 1. Login to Azure
+From a command (or PowerShell) prompt in the root of the bot folder, execute:  
+`az login`
+  
+### 2. Set the subscription
+`az account set --subscription "<azure-subscription>"`
+
+If you aren't sure which subscription to use for deploying the bot, you can view the list of subscriptions for your account by using `az account list` command. 
+
+### 3. Create an App registration
+`az ad app create --display-name "<botname>" --password "<appsecret>" --available-to-other-tenants`
+
+Replace `<botname>` and `<appsecret>` with your own values.
+
+`<botname>` is the unique name of your bot.  
+`<appsecret>` is a minimum 16 character password for your bot. 
+
+Record the `appid` from the returned JSON
+
+### 4. Create the Azure resources
+Replace the values for `<appid>`, `<appsecret>`, `<botname>`, and `<groupname>` in the following commands:
+
+#### To a new Resource Group
+`az deployment sub create --name "echoBotDeploy" --location "westus" --template-file ".\deploymentTemplates\template-with-new-rg.json" --parameters appId="<appid>" appSecret="<appsecret>" botId="<botname>" botSku=S1 newAppServicePlanName="echoBotPlan" newWebAppName="echoBot" groupLocation="westus" newAppServicePlanLocation="westus"` 
+
+#### To an existing Resource Group
+`az deployment group create --resource-group "<groupname>" --template-file ".\deploymentTemplates\template-with-preexisting-rg.json" --parameters appId="<appid>" appSecret="<appsecret>" botId="<botname>" newWebAppName="echoBot" newAppServicePlanName="echoBotPlan" appServicePlanLocation="westus" --name "echoBot"`
+
+### 5. Update app id and password
+In src/main/resources/application.properties update 
+  - `MicrosoftAppPassword` with the botsecret value
+  - `MicrosoftAppId` with the appid from the first step
+
+### 6. Deploy the code
+- Execute `mvn clean package` 
+- Execute `mvn azure-webapp:deploy -Dgroupname="<groupname>" -Dbotname="<botname>"`
+
+If the deployment is successful, you will be able to test it via "Test in Web Chat" from the Azure Portal using the "Bot Channel Registration" for the bot.
+
+After the bot is deployed, you only need to execute #6 if you make changes to the bot.
+
+
+## Further reading
+
+- [Maven Plugin for Azure App Service](https://docs.microsoft.com/en-us/java/api/overview/azure/maven/azure-webapp-maven-plugin/readme?view=azure-java-stable)
+- [Spring Boot](https://spring.io/projects/spring-boot)
+- [Azure for Java cloud developers](https://docs.microsoft.com/en-us/azure/java/?view=azure-java-stable)
+- [Bot Framework Documentation](https://docs.botframework.com)
+- [Bot Basics](https://docs.microsoft.com/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0)
+- [Attachments](https://docs.microsoft.com/en-us/azure/bot-service/nodejs/bot-builder-nodejs-send-receive-attachments?view=azure-bot-service-4.0)
+- [Activity processing](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-activity-processing?view=azure-bot-service-4.0)
+- [Azure Bot Service Introduction](https://docs.microsoft.com/azure/bot-service/bot-service-overview-introduction?view=azure-bot-service-4.0)
+- [Azure Bot Service Documentation](https://docs.microsoft.com/azure/bot-service/?view=azure-bot-service-4.0)
+- [Azure CLI](https://docs.microsoft.com/cli/azure/?view=azure-cli-latest)
+- [Azure Portal](https://portal.azure.com)
+- [Channels and Bot Connector Service](https://docs.microsoft.com/en-us/azure/bot-service/bot-concepts?view=azure-bot-service-4.0)