Merge pull request #88065 from ecfan/request

Update UX and steps for Request trigger / Response action

Author: PMEds28

articles/connectors/connectors-native-reqres.md

@@ -1,111 +1,220 @@
 ---
-title: Use request and response actions | Microsoft Docs
-description: Overview of the request and response trigger and action in an Azure logic app
-services: ''
-documentationcenter: ''
-author: jeffhollan
-manager: erikre
-editor: ''
-tags: connectors
-
-ms.assetid: 566924a4-0988-4d86-9ecd-ad22507858c0
+title: Respond to HTTP or HTTPS requests - Azure Logic Apps
+description: Respond to events in real time over HTTP or HTTPS by using Azure Logic Apps
+services: logic-apps
 ms.service: logic-apps
-ms.devlang: na
+ms.suite: integration
+author: ecfan
+ms.author: estfan
+ms.reviewers: klam, LADocs
+manager: carmonm
+ms.assetid: 566924a4-0988-4d86-9ecd-ad22507858c0
 ms.topic: article
-ms.tgt_pltfrm: na
-ms.workload: na
-ms.date: 07/18/2016
-ms.author: jehollan
-
+ms.date: 09/06/2019
+tags: connectors
 ---
-# Get started with the request and response components
-With the request and response components in a logic app, you can respond in real time to events.
 
-For example, you can:
+# Respond to HTTP or HTTPS requests by using Azure Logic Apps
+
+With [Azure Logic Apps](../logic-apps/logic-apps-overview.md) and the built-in Request trigger or Response action, you can create automated tasks and workflows that react and respond in real time to events that are sent over HTTP or HTTPS. For example, you can have your logic app:
+
+* Respond to an HTTP request for data in an on-premises database.
+* Trigger a workflow when an external webhook event happens.
+* Call a logic app from within another logic app.
+
+## Prerequisites
+
+* An Azure subscription. If you don't have a subscription, you can [sign up for a free Azure account](https://azure.microsoft.com/free/).
+
+* Basic knowledge about [logic apps](../logic-apps/logic-apps-overview.md). If you're new to logic apps, learn [how to create your first logic app](../logic-apps/quickstart-create-first-logic-app-workflow.md).
+
+<a name="add-request"></a>
+
+## Add the Request trigger
+
+This built-in trigger creates an endpoint that waits for and receives an incoming request over HTTP or HTTPS. When this event happens, the trigger fires and runs the logic app.
+
+1. Sign in to the [Azure portal](https://portal.azure.com). Create a blank logic app.
+
+1. After Logic App Designer opens, in the search box, enter "http request" as your filter. From the triggers list, select the **When an HTTP request is received** trigger, which is the first step in your logic app workflow.
+
+   ![Select HTTP request trigger](./media/connectors-native-reqres/select-request-trigger.png)
+
+1. For the **Request Body JSON Schema** box, you can optionally enter a JSON schema that describes the HTTP request body that's expected in the incoming request, for example:
+
+   ![Example JSON schema](./media/connectors-native-reqres/provide-json-schema.png)
+
+   The designer uses this schema to generate tokens for the properties in the request. That way, your logic app can parse, consume, and pass along data from the request through the trigger into your workflow.
+
+   Here is the sample schema:
 
-* Respond to an HTTP request with data from an on-premises database through a logic app.
-* Trigger a logic app from an external webhook event.
-* Call a logic app with a request and response action from within another logic app.
+   ```json
+   {
+      "type": "object",
+      "properties": {
+         "account": {
+            "type": "object",
+            "properties": {
+               "name": {
+                  "type": "string"
+               },
+               "ID": {
+                  "type": "string"
+               },
+               "address": {
+                  "type": "object",
+                  "properties": {
+                     "number": {
+                        "type": "string"
+                     },
+                     "street": {
+                        "type": "string"
+                     },
+                     "city": {
+                        "type": "string"
+                     },
+                     "state": {
+                        "type": "string"
+                     },
+                     "country": {
+                        "type": "string"
+                     },
+                     "postalCode": {
+                        "type": "string"
+                     }
+                  }
+               }
+            }
+         }
+      }
+   }
+   ```
 
-To get started using the request and response actions in a logic app, see [Create a logic app](../logic-apps/quickstart-create-first-logic-app-workflow.md).
+   When you enter a JSON schema, the designer shows a reminder to include the `Content-Type` header in your request and set that header value to `application/json`. For more information, see [Handle content types](../logic-apps/logic-apps-content-type.md).
 
-## Use the HTTP Request trigger
-A trigger is an event that can be used to start the workflow that is defined in a logic app. 
-[Learn more about triggers](../connectors/apis-list.md).
+   ![Reminder to include "Content-Type" header](./media/connectors-native-reqres/include-content-type.png)
 
-Here's an example sequence of how to set up an HTTP request in the Logic App Designer.
+   Here's what this header looks like in JSON format:
 
-1. Add the trigger **Request - When an HTTP request is received** in your logic app. You can optionally provide a JSON schema (by using a tool like [JSONSchema.net](https://jsonschema.net)) for the request body. This allows the designer to generate tokens for properties in the HTTP request.
-2. Add another action so that you can save the logic app.
-3. After saving the logic app, you can get the HTTP request URL from the request card.
-4. An HTTP POST (you can use a tool like [Postman](https://www.getpostman.com/)) to the URL triggers the logic app.
+   ```json
+   {
+      "Content-Type": "application/json"
+   }
+   ```
 
-> [!NOTE]
-> If you don't define a response action, a `202 ACCEPTED` response is immediately returned to the caller. You can use the response action to customize a response.
-> 
-> 
+   To generate a JSON schema that's based on the expected payload (data), you can use a tool such as [JSONSchema.net](https://jsonschema.net), or you can follow these steps:
 
-![Response trigger](./media/connectors-native-reqres/using-trigger.png)
+   1. In the Request trigger, select **Use sample payload to generate schema**.
 
-## Use the HTTP Response action
-The HTTP Response action is only valid when you use it in a workflow that is triggered by an HTTP request. If you don't define a response action, a `202 ACCEPTED` response is immediately returned to the caller.  You can add a response action at any step within the workflow. The logic app only keeps the incoming request open for one minute for a response.  After one minute, if no response was sent from the workflow (and a response action exists in the definition), a `504 GATEWAY TIMEOUT` is returned to the caller.
+      ![Generate schema from payload](./media/connectors-native-reqres/generate-from-sample-payload.png)
 
-Here's how to add an HTTP Response action:
+   1. Enter the sample payload, and select **Done**.
 
-1. Select the **New Step** button.
-2. Choose **Add an action**.
-3. In the action search box, type **response** to list the Response action.
-   
-    ![Select the response action](./media/connectors-native-reqres/using-action-1.png)
-4. Add in any parameters that are required for the HTTP response message.
-   
-    ![Complete the response action](./media/connectors-native-reqres/using-action-2.png)
-5. Click the upper-left corner of the toolbar to save, and your logic app will both save and publish (activate).
+      ![Generate schema from payload](./media/connectors-native-reqres/enter-payload.png)
 
-## Request trigger
-Here are the details for the trigger that this connector supports. There is a single request trigger.
+      Here is the sample payload:
 
-| Trigger | Description |
-| --- | --- |
-| Request |Occurs when an HTTP request is received |
+      ```json
+      {
+         "account": {
+            "name": "Contoso",
+            "ID": "12345",
+            "address": { 
+               "number": "1234",
+               "street": "Anywhere Street",
+               "city": "AnyTown",
+               "state": "AnyState",
+               "country": "USA",
+               "postalCode": "11111"
+            }
+         }
+      }
+      ```
 
-## Response action
-Here are the details for the action that this connector supports. There is a single response action that can only be used when it is accompanied by a request trigger.
+1. To specify additional properties, such as the expected method used for the request or a relative path, open the **Add new parameter** list, and select the parameters that you want to add.
 
-| Action | Description |
-| --- | --- |
-| Response |Returns a response to the correlated HTTP request |
+   This example adds the **Method** parameter:
 
-### Trigger and action details
-The following tables describe the input fields for the trigger and action, and the corresponding output details.
+   ![Add Method parameter](./media/connectors-native-reqres/add-parameters.png)
 
-#### Request trigger
-The following is an input field for the trigger from an incoming HTTP request.
+   Now the **Method** parameter appears in the trigger so that you can select a method from the list.
 
-| Display name | Property name | Description |
-| --- | --- | --- |
-| JSON Schema |schema |The JSON schema of the HTTP request body |
+   ![Select method](./media/connectors-native-reqres/select-method.png)
 
-<br>
+1. Now, add another action as the next step in your workflow. Under the trigger, select **Next step** so that you can find the action that you want to add.
+
+   For example, you can respond to the request by [adding a Response action](#add-response), which is described later in this topic.
+
+   > [!NOTE]
+   > If you don't include and define a Response action in your logic app workflow, 
+   > your logic app immediately returns a `202 ACCEPTED` response to the caller. 
+   > You can use the Response action to customize a response.
+
+1. When you're done, save your logic app. On the designer toolbar, select **Save**. 
+
+   This step generates the URL to use for sending the request that triggers the logic app. To copy this URL, select the copy icon next to the URL.
+
+   ![URL to use triggering your logic app](./media/connectors-native-reqres/generated-url.png)
 
-**Output details**
+1. To trigger your logic app, send an HTTP POST to the generated URL. For example, you can use a tool such as [Postman](https://www.getpostman.com/).
 
-The following are output details for the request.
+### Trigger outputs
+
+Here's more information about the outputs from the Request trigger:
 
 | Property name | Data type | Description |
-| --- | --- | --- |
-| Headers |object |Request headers |
-| Body |object |Request object |
+|---------------|-----------|-------------|
+| `headers` | Object | A JSON object that describes the headers from the request |
+| `body` | Object | A JSON object that describes the body content from the request |
+||||
+
+<a name="add-response"></a>
+
+## Add a Response action
+
+You can use the Response action to customize a response but only in a logic app workflow that's triggered by an HTTP request. You can add the Response action at any point in your workflow.
+
+Your logic app keeps the incoming request open only for one minute. Assuming that your logic app workflow includes a Response action, if the logic app doesn't return a response after this time passes, your logic app returns a `504 GATEWAY TIMEOUT` to the caller. However, if your logic app doesn't include a Response action, your logic app immediately returns a `202 ACCEPTED` response to the caller. 
+
+1. In the Logic App Designer, under the step where you want to add a Response action, select **New step**.
+
+   For example, using the Request trigger from earlier:
+
+   ![Add new step](./media/connectors-native-reqres/add-response.png)
+
+   To add an action between steps, move your pointer over the arrow between those steps. Select the plus sign (**+**) that appears, and then select **Add an action**.
+
+1. Under **Choose an action**, in the search box, enter "response" as your filter, and select the **Response** action.
+
+   ![Select the Response action](./media/connectors-native-reqres/select-response-action.png)
+
+   The Request trigger is collapsed in this example for simplicity.
+
+1. Add any values that are required for the response message. 
+
+   In some fields, clicking inside their boxes opens the dynamic content list. You can then select tokens that represent available outputs from previous steps in the workflow. Properties from the schema specified in the earlier example now appear in the dynamic content list.
+
+   For example, in the **Headers** field, include `Content-Type` as the key name and set the key value to `application/json`, as mentioned earlier in this topic. For the **Body** field, you can select the trigger body from the dynamic content list.
+
+   ![Response action details](./media/connectors-native-reqres/response-details.png)
+
+   To view the headers in JSON format, select **Switch to text view**.
+
+   ![Headers - Switch to text view](./media/connectors-native-reqres/switch-to-text-view.png)
+
+   Here is more information about the properties that you can set in the Response action. 
+
+   | Display name | Property name | Required | Description |
+   |--------------|---------------|----------|-------------|
+   | Status Code | `statusCode` | Yes | The HTTP status code to return |
+   | Headers | `headers` | No | A JSON object that describes any response headers to include.  |
+   | Body | `body` | No | The response body |
+   |||||
 
-#### Response action
-The following are input fields for the HTTP Response action. A * means that it is a required field.
+1. To specify additional properties, such as a JSON schema for the response, open the **Add new parameter** list, and select the parameters that you want to add.
 
-| Display name | Property name | Description |
-| --- | --- | --- |
-| Status Code* |statusCode |The HTTP status code |
-| Headers |headers |A JSON object of any response headers to include |
-| Body |body |The response body |
+1. When you're done, save your logic app. On the designer toolbar, select **Save**. 
 
 ## Next steps
-Now, try out the platform and [create a logic app](../logic-apps/quickstart-create-first-logic-app-workflow.md). You can explore the other available connectors in logic apps by looking at our [APIs list](apis-list.md).
 
+* [Connectors for Logic Apps](../connectors/apis-list.md)