Create a custom connector from scratch

• 11/18/2017
• 6 minutes to read
• • 
  • 
  • 

To create a custom connector, you must describe the API you want to connect to so that the connector understands the API's operations and data structures. In this topic, you create a custom connector from scratch, without using a Postman collection or an OpenAPI definition to describe the Cognitive Services Text Analytics Sentiment API (our example for this series). Instead, you describe the connector completely in the custom connector wizard.

For other ways to describe an API, see the following topics:

• Create a custom connector from an OpenAPI definition
• Create a custom connector from a Postman collection

Prerequisites

• An API key for the Cognitive Services Text Analytics API
• One of the following subscriptions:
  • Microsoft Flow
  • PowerApps

Start the custom connector wizard

1. Go to powerapps.com or flow.microsoft.com.

2. In the upper right corner, choose the gear icon, then choose Custom connectors.

   

3. Choose Create custom connector, then choose Create from blank.

   

4. Enter a name for the custom connector, then choose Connect.

   

   Parameter	Value
   Custom connector title	"SentimentDemo"

Update general details

From this point, we'll show the Microsoft Flow UI, but the steps are largely the same across the technologies. We'll point out any differences.

1. On the General page:

   • Enter a meaningful value for Description. This description is displayed in the custom connector's details, and it can help others know if the connector could be useful to them.

   • Update Host to the address for the Text Analytics API. The connector uses the API host and the base URL to determine how to call the API.

   

   Parameter	Value
   Description	"Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
   Host	"westus.api.cognitive.microsoft.com"

   Note

   For more information about the option Connect via on-premises data gateway, see Connect to on-premises APIs using the data gateway.

Specify authentication type

There are several options available for authentication in custom connectors. The Cognitive Services APIs use API key authentication, so that's what you specify for this tutorial.

1. On the Security page, under Authentication type, choose API Key.

   

2. Under API Key, specify a parameter label, name, and location. Specify a meaningful label, because this is displayed when someone first makes a connection with the custom connector. The parameter name and location must match what the API expects. Choose Connect.

   

   Parameter	Value
   Parameter label	"API key"
   Parameter name	"Ocp-Apim-Subscription-Key"
   Parameter location	"Header"

3. At the top of the wizard, make sure the name is set to "SentimentDemo", then choose Create connector.

Create the connector definition

The custom connector wizard gives you a lot of options for defining how your connector functions, and how it is exposed in logic apps, flows, and apps. We'll explain the UI and cover a few options in this section, but we also encourage you to explore on your own.

Create an action

The first thing to do is create an action that calls the Text Analytics Sentiment API.

1. On the Definition page, the left area displays any actions, triggers (for Logic Apps and Microsoft Flow), and references that are defined for the connector. Choose New action.

   

   There are no triggers in this connector, but you can learn about triggers for custom connectors in Use webhooks with Azure Logic Apps and Microsoft Flow.

2. The General area displays information about the action or trigger currently selected. Add a summary, description, and operation ID for this action.

   

   Parameter	Value
   Summary	"Returns a numeric score representing the sentiment detected"
   Description	"The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment."
   Operation ID	"DetectSentiment"

   Leave the Visibility property set to none. This property for operations and parameters in a logic app or flow has the following options:

   • none: displayed normally in the logic app or flow
   • advanced: hidden under an additional menu
   • internal: hidden from the user
   • important: always shown to the user first

3. The Request area displays information based on the HTTP request for the action. Choose Import from sample.

   

4. Specify the information necessary to connect to the API, and the request body, then choose Import. We provide this information for you (below the image). For a public API, you typically get it from the documentation, like Text Analytics Sentiment API.

   

   Parameter	Value
   Verb	"POST"
   URL	"https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment"
   Body	See below

   {
     "documents": [
       {
         "language": "string",
         "id": "string",
         "text": "string"
       }
     ]
   }
   

5. The Response area displays information based on the HTTP response for the action. Choose Add default response.

   

6. Specify the response body, then choose Import. Like the request, we provide this information for you, but it's typically in the API documentation.

   

   {
    "documents": [
      {
        "score": 0.0,
        "id": "string"
      }
    ],
    "errors": [
      {
        "id": "string",
        "message": "string"
      }
    ]
   }
   

7. The Validation area displays any issues that are detected in the API definition. Check the status, then at the top right of the wizard, choose Update connector.

   

Update the definition

Now let's change a few things so that the connector is more friendly when someones uses it in a logic app, flow, or PowerApps app.

1. In the Request area, choose body then Edit.

   

2. In the Parameter area, you now see the three parameters that the API expects: id, language, and text. Choose id then Edit.

   

3. In the Schema Property area, update values for the parameter, then choose Back.

   

   Parameter	Value
   Title	"ID"
   Description	"An identifier for each document that you submit"
   Default value	"1"
   Is required	"Yes"

4. In the Parameter area, choose language then Edit, and repeat the process you used for id, with the following values.

   Parameter	Value
   Title	"Language"
   Description	"The 2 or 4 character language code for the text"
   Default value	"en"
   Is required	"Yes"

5. In the Parameter area, choose text then Edit, and repeat the process you used for id and language, with the following values.

   Parameter	Value
   Title	"Text"
   Description	"The text to analyze for sentiment"
   Default value	None
   Is required	"Yes"

6. In the Parameter area, choose Back to take you back to the main definition page.

7. At the top right of the wizard, choose Update connector.

Test the connector

Now that you've created the connector, test it to make sure it's working properly. Testing is currently available only in Microsoft Flow and PowerApps.

1. On the Test page, choose New connection.

   

2. Enter the API key from the Text Analytics API, then choose Create connection.

   

3. Return to the Test page:

   • In Microsoft Flow, you are taken back to the Test page. Choose the refresh icon to make sure the connection information is updated.

     

   • In PowerApps, you are taken to the list of connections available in the current environment. In the upper right corner, choose the gear icon, then choose Custom connectors. Choose the connector you created, then go back to the Test page.

     

4. On the Test page, enter a value for the text field (the other fields use the defaults that you set earlier), then choose Test operation.

   

5. The connector calls the API, and you can review the response, which includes the sentiment score.

   

Next steps

Now that you've created a custom connector and defined its behaviors, you can use the connector:

• Use a custom connector from a flow
• Use a custom connector from a PowerApps app
• Use a custom connector from a logic app

You can also share a connector within your organization and/or get the connector certified so that people outside your organization can use it:

• Share your connector
• Certify your connector