Quickstart: Entity Linking using the client library and REST API
Reference documentation | Additional samples | Package (NuGet) | Library source code
Use this quickstart to create an entity linking application with the client library for .NET. In the following example, you will create a C# application that can identify and disambiguate entities found in text.
Tip
You can use Language Studio to try Language service features without needing to write code.
Prerequisites
- Azure subscription - Create one for trial
- The Visual Studio IDE
- Once you have your Azure subscription, create a Language resource in the Azure portal to get your key and endpoint. After it deploys, select Go to resource.
- You will need the key and endpoint from the resource you create to connect your application to the API. You'll paste your key and endpoint into the code below later in the quickstart.
- You can use the free pricing tier (
Free F0
) to try the service, and upgrade later to a paid tier for production.
- To use the Analyze feature, you will need a Language resource with the standard (S) pricing tier.
Setting up
Create a new .NET Core application
Using the Visual Studio IDE, create a new .NET Core console app. This will create a "Hello World" project with a single C# source file: program.cs.
Install the client library by right-clicking on the solution in the Solution Explorer and selecting Manage NuGet Packages. In the package manager that opens select Browse and search for Azure.AI.TextAnalytics
. Select version 5.2.0
, and then Install. You can also use the Package Manager Console.
Code example
Copy the following code into your program.cs file. Remember to replace the key
variable with the key for your resource, and replace the endpoint
variable with the endpoint for your resource. Then run the code.
Important
Go to the Azure portal. If the Language resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint by navigating to your resource's Keys and Endpoint page, under Resource Management.
Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.
using Azure;
using System;
using System.Globalization;
using Azure.AI.TextAnalytics;
namespace EntityLinkingExample
{
class Program
{
private static readonly Uri endpoint = new Uri("replace-with-your-endpoint-here");
private static readonly AzureKeyCredential credentials = new AzureKeyCredential("replace-with-your-key-here");
// Example method for recognizing entities and providing a link to an online data source.
static void EntityLinkingExample(TextAnalyticsClient client)
{
var response = client.RecognizeLinkedEntities(
"Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, " +
"to develop and sell BASIC interpreters for the Altair 8800. " +
"During his career at Microsoft, Gates held the positions of chairman, " +
"chief executive officer, president and chief software architect, " +
"while also being the largest individual shareholder until May 2014.");
Console.WriteLine("Linked Entities:");
foreach (var entity in response.Value)
{
Console.WriteLine($"\tName: {entity.Name},\tID: {entity.DataSourceEntityId},\tURL: {entity.Url}\tData Source: {entity.DataSource}");
Console.WriteLine("\tMatches:");
foreach (var match in entity.Matches)
{
Console.WriteLine($"\t\tText: {match.Text}");
Console.WriteLine($"\t\tScore: {match.ConfidenceScore:F2}\n");
}
}
}
static void Main(string[] args)
{
var client = new TextAnalyticsClient(endpoint, credentials);
EntityLinkingExample(client);
Console.Write("Press any key to exit.");
Console.ReadKey();
}
}
}
Output
Linked Entities:
Name: Microsoft, ID: Microsoft, URL: https://en.wikipedia.org/wiki/Microsoft Data Source: Wikipedia
Matches:
Text: Microsoft
Score: 0.55
Text: Microsoft
Score: 0.55
Name: Bill Gates, ID: Bill Gates, URL: https://en.wikipedia.org/wiki/Bill_Gates Data Source: Wikipedia
Matches:
Text: Bill Gates
Score: 0.63
Text: Gates
Score: 0.63
Name: Paul Allen, ID: Paul Allen, URL: https://en.wikipedia.org/wiki/Paul_Allen Data Source: Wikipedia
Matches:
Text: Paul Allen
Score: 0.60
Name: April 4, ID: April 4, URL: https://en.wikipedia.org/wiki/April_4 Data Source: Wikipedia
Matches:
Text: April 4
Score: 0.32
Name: BASIC, ID: BASIC, URL: https://en.wikipedia.org/wiki/BASIC Data Source: Wikipedia
Matches:
Text: BASIC
Score: 0.33
Name: Altair 8800, ID: Altair 8800, URL: https://en.wikipedia.org/wiki/Altair_8800 Data Source: Wikipedia
Matches:
Text: Altair 8800
Score: 0.88
Clean up resources
If you want to clean up and remove an Azure AI services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.
Next steps
Reference documentation | Additional samples | Package (Maven) | Library source code
Use this quickstart to create an entity linking application with the client library for Java. In the following example, you will create a Java application that can identify and disambiguate entities found in text.
Tip
You can use Language Studio to try Language service features without needing to write code.
Prerequisites
- Azure subscription - Create one for trial
- Java Development Kit (JDK) with version 8 or above
- Once you have your Azure subscription, create a Language resource in the Azure portal to get your key and endpoint. After it deploys, select Go to resource.
- You will need the key and endpoint from the resource you create to connect your application to the API. You'll paste your key and endpoint into the code below later in the quickstart.
- You can use the free pricing tier (
Free F0
) to try the service, and upgrade later to a paid tier for production.
- To use the Analyze feature, you will need a Language resource with the standard (S) pricing tier.
Setting up
Add the client library
Create a Maven project in your preferred IDE or development environment. Then add the following dependency to your project's pom.xml file. You can find the implementation syntax for other build tools online.
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-textanalytics</artifactId>
<version>5.2.0</version>
</dependency>
</dependencies>
Code example
Create a Java file named Example.java
. Open the file and copy the below code. Remember to replace the key
variable with the key for your resource, and replace the endpoint
variable with the endpoint for your resource. Then run the code.
Important
Go to the Azure portal. If the Language resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint by navigating to your resource's Keys and Endpoint page, under Resource Management.
Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.
import com.azure.core.credential.AzureKeyCredential;
import com.azure.ai.textanalytics.models.*;
import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
import com.azure.ai.textanalytics.TextAnalyticsClient;
public class Example {
private static String KEY = "replace-with-your-key-here";
private static String ENDPOINT = "replace-with-your-endpoint-here";
public static void main(String[] args) {
TextAnalyticsClient client = authenticateClient(KEY, ENDPOINT);
recognizeLinkedEntitiesExample(client);
}
// Method to authenticate the client object with your key and endpoint
static TextAnalyticsClient authenticateClient(String key, String endpoint) {
return new TextAnalyticsClientBuilder()
.credential(new AzureKeyCredential(key))
.endpoint(endpoint)
.buildClient();
}
// Example method for recognizing entities and providing a link to an online data source
static void recognizeLinkedEntitiesExample(TextAnalyticsClient client)
{
// The text that need be analyzed.
String text = "Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, " +
"to develop and sell BASIC interpreters for the Altair 8800. " +
"During his career at Microsoft, Gates held the positions of chairman, " +
"chief executive officer, president and chief software architect, " +
"while also being the largest individual shareholder until May 2014.";
System.out.printf("Linked Entities:%n");
for (LinkedEntity linkedEntity : client.recognizeLinkedEntities(text)) {
System.out.printf("Name: %s, ID: %s, URL: %s, Data Source: %s.%n",
linkedEntity.getName(),
linkedEntity.getDataSourceEntityId(),
linkedEntity.getUrl(),
linkedEntity.getDataSource());
System.out.printf("Matches:%n");
for (LinkedEntityMatch linkedEntityMatch : linkedEntity.getMatches()) {
System.out.printf("Text: %s, Score: %.2f, Offset: %s, Length: %s%n",
linkedEntityMatch.getText(),
linkedEntityMatch.getConfidenceScore(),
linkedEntityMatch.getOffset(),
linkedEntityMatch.getLength());
}
}
}
}
Output
Linked Entities:
Name: Microsoft, ID: Microsoft, URL: https://en.wikipedia.org/wiki/Microsoft, Data Source: Wikipedia.
Matches:
Text: Microsoft, Score: 0.55, Offset: 0, Length: 9
Text: Microsoft, Score: 0.55, Offset: 150, Length: 9
Name: Bill Gates, ID: Bill Gates, URL: https://en.wikipedia.org/wiki/Bill_Gates, Data Source: Wikipedia.
Matches:
Text: Bill Gates, Score: 0.63, Offset: 25, Length: 10
Text: Gates, Score: 0.63, Offset: 161, Length: 5
Name: Paul Allen, ID: Paul Allen, URL: https://en.wikipedia.org/wiki/Paul_Allen, Data Source: Wikipedia.
Matches:
Text: Paul Allen, Score: 0.60, Offset: 40, Length: 10
Name: April 4, ID: April 4, URL: https://en.wikipedia.org/wiki/April_4, Data Source: Wikipedia.
Matches:
Text: April 4, Score: 0.32, Offset: 54, Length: 7
Name: BASIC, ID: BASIC, URL: https://en.wikipedia.org/wiki/BASIC, Data Source: Wikipedia.
Matches:
Text: BASIC, Score: 0.33, Offset: 89, Length: 5
Name: Altair 8800, ID: Altair 8800, URL: https://en.wikipedia.org/wiki/Altair_8800, Data Source: Wikipedia.
Matches:
Text: Altair 8800, Score: 0.88, Offset: 116, Length: 11
Clean up resources
If you want to clean up and remove an Azure AI services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.
Next steps
Reference documentation | Additional samples | Package (npm) | Library source code
Use this quickstart to create an entity linking application with the client library for Node.js. In the following example, you will create a JavaScript application that can identify and disambiguate entities found in text.
Tip
You can use Language Studio to try Language service features without needing to write code.
Prerequisites
- Azure subscription - Create one for trial
- Node.js v14 LTS or later
- Once you have your Azure subscription, create a Language resource in the Azure portal to get your key and endpoint. After it deploys, select Go to resource.
- You will need the key and endpoint from the resource you create to connect your application to the API. You'll paste your key and endpoint into the code below later in the quickstart.
- You can use the free pricing tier (
Free F0
) to try the service, and upgrade later to a paid tier for production.
- To use the Analyze feature, you will need a Language resource with the standard (S) pricing tier.
Setting up
Create a new Node.js application
In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it.
mkdir myapp
cd myapp
Run the npm init
command to create a node application with a package.json
file.
npm init
Install the client library
Install the npm package:
npm install @azure/ai-language-text
Code example
Open the file and copy the below code. Remember to replace the key
variable with the key for your resource, and replace the endpoint
variable with the endpoint for your resource. Then run the code.
Important
Go to the Azure portal. If the Language resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint by navigating to your resource's Keys and Endpoint page, under Resource Management.
Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.
"use strict";
const { TextAnalysisClient, AzureKeyCredential } = require("@azure/ai-language-text");
const endpoint = '<paste-your-endpoint-here>';
const key = '<paste-your-key-here>';
//example sentence for recognizing entities
const documents = ["Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975."];
//example of how to use the client to perform entity linking on a document
async function main() {
console.log("== Entity linking sample ==");
const client = new TextAnalysisClient(endpoint, new AzureKeyCredential(key));
const results = await client.analyze("EntityLinking", documents);
for (const result of results) {
console.log(`- Document ${result.id}`);
if (!result.error) {
console.log("\tEntities:");
for (const entity of result.entities) {
console.log(
`\t- Entity ${entity.name}; link ${entity.url}; datasource: ${entity.dataSource}`
);
console.log("\t\tMatches:");
for (const match of entity.matches) {
console.log(
`\t\t- Entity appears as "${match.text}" (confidence: ${match.confidenceScore}`
);
}
}
} else {
console.error(" Error:", result.error);
}
}
}
//call the main function
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
Output
== Entity linking sample ==
- Document 0
Entities:
- Entity Microsoft; link https://en.wikipedia.org/wiki/Microsoft; datasource: Wikipedia
Matches:
- Entity appears as "Microsoft" (confidence: 0.48
- Entity Bill Gates; link https://en.wikipedia.org/wiki/Bill_Gates; datasource: Wikipedia
Matches:
- Entity appears as "Bill Gates" (confidence: 0.52
- Entity Paul Allen; link https://en.wikipedia.org/wiki/Paul_Allen; datasource: Wikipedia
Matches:
- Entity appears as "Paul Allen" (confidence: 0.54
- Entity April 4; link https://en.wikipedia.org/wiki/April_4; datasource: Wikipedia
Matches:
- Entity appears as "April 4" (confidence: 0.38
Clean up resources
If you want to clean up and remove an Azure AI services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.
Next steps
Reference documentation | Additional samples | Package (PyPi) | Library source code
Use this quickstart to create an entity linking application with the client library for Python. In the following example, you will create a Python application that can identify and disambiguate entities found in text.
Tip
You can use Language Studio to try Language service features without needing to write code.
Prerequisites
- Azure subscription - Create one for trial
- Python 3.7 or later
- Once you have your Azure subscription, create a Language resource in the Azure portal to get your key and endpoint. After it deploys, select Go to resource.
- You will need the key and endpoint from the resource you create to connect your application to the API. You'll paste your key and endpoint into the code below later in the quickstart.
- You can use the free pricing tier (
Free F0
) to try the service, and upgrade later to a paid tier for production.
- To use the Analyze feature, you will need a Language resource with the standard (S) pricing tier.
Setting up
Install the client library
After installing Python, you can install the client library with:
pip install azure-ai-textanalytics==5.2.0
Code example
Create a new Python file and copy the below code. Remember to replace the key
variable with the key for your resource, and replace the endpoint
variable with the endpoint for your resource. Then run the code.
Important
Go to the Azure portal. If the Language resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint by navigating to your resource's Keys and Endpoint page, under Resource Management.
Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.
endpoint = "paste-your-endpoint-here"
key = "paste-your-key-here"
from azure.ai.textanalytics import TextAnalyticsClient
from azure.core.credentials import AzureKeyCredential
# Authenticate the client using your key and endpoint.
def authenticate_client():
ta_credential = AzureKeyCredential(key)
text_analytics_client = TextAnalyticsClient(
endpoint=endpoint,
credential=ta_credential)
return text_analytics_client
client = authenticate_client()
# Example function for recognizing entities and providing a link to an online data source.
def entity_linking_example(client):
try:
documents = ["""Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975,
to develop and sell BASIC interpreters for the Altair 8800.
During his career at Microsoft, Gates held the positions of chairman,
chief executive officer, president and chief software architect,
while also being the largest individual shareholder until May 2014."""]
result = client.recognize_linked_entities(documents = documents)[0]
print("Linked Entities:\n")
for entity in result.entities:
print("\tName: ", entity.name, "\tId: ", entity.data_source_entity_id, "\tUrl: ", entity.url,
"\n\tData Source: ", entity.data_source)
print("\tMatches:")
for match in entity.matches:
print("\t\tText:", match.text)
print("\t\tConfidence Score: {0:.2f}".format(match.confidence_score))
print("\t\tOffset: {}".format(match.offset))
print("\t\tLength: {}".format(match.length))
except Exception as err:
print("Encountered exception. {}".format(err))
entity_linking_example(client)
Output
Linked Entities:
Name: Microsoft Id: Microsoft Url: https://en.wikipedia.org/wiki/Microsoft
Data Source: Wikipedia
Matches:
Text: Microsoft
Confidence Score: 0.55
Offset: 0
Length: 9
Text: Microsoft
Confidence Score: 0.55
Offset: 168
Length: 9
Name: Bill Gates Id: Bill Gates Url: https://en.wikipedia.org/wiki/Bill_Gates
Data Source: Wikipedia
Matches:
Text: Bill Gates
Confidence Score: 0.63
Offset: 25
Length: 10
Text: Gates
Confidence Score: 0.63
Offset: 179
Length: 5
Name: Paul Allen Id: Paul Allen Url: https://en.wikipedia.org/wiki/Paul_Allen
Data Source: Wikipedia
Matches:
Text: Paul Allen
Confidence Score: 0.60
Offset: 40
Length: 10
Name: April 4 Id: April 4 Url: https://en.wikipedia.org/wiki/April_4
Data Source: Wikipedia
Matches:
Text: BASIC
Confidence Score: 0.33
Offset: 98
Length: 5
Name: Altair 8800 Id: Altair 8800 Url: https://en.wikipedia.org/wiki/Altair_8800
Data Source: Wikipedia
Matches:
Text: Altair 8800
Confidence Score: 0.88
Offset: 125
Length: 11
Clean up resources
If you want to clean up and remove an Azure AI services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.
Next steps
Use this quickstart to send entity linking requests using the REST API. In the following example, you will use cURL to identify and disambiguate entities found in text.
Tip
You can use Language Studio to try Language service features without needing to write code.
Prerequisites
- The current version of cURL.
- Once you have your Azure subscription, create a Language resource in the Azure portal to get your key and endpoint. After it deploys, select Go to resource.
- You will need the key and endpoint from the resource you create to connect your application to the API. You'll paste your key and endpoint into the code below later in the quickstart.
- You can use the free pricing tier (
Free F0
) to try the service, and upgrade later to a paid tier for production.
Note
- The following BASH examples use the
\
line continuation character. If your console or terminal uses a different line continuation character, use that character. - You can find language specific samples on GitHub.
- Go to the Azure portal and find the key and endpoint for the Language resource you created in the prerequisites. They will be located on the resource's key and endpoint page, under resource management. Then replace the strings in the code below with your key and endpoint. To call the API, you need the following information:
parameter | Description |
---|---|
-X POST <endpoint> |
Specifies your endpoint for accessing the API. |
-H Content-Type: application/json |
The content type for sending JSON data. |
-H "Ocp-Apim-Subscription-Key:<key> |
Specifies the key for accessing the API. |
-d <documents> |
The JSON containing the documents you want to send. |
The following cURL commands are executed from a BASH shell. Edit these commands with your own resource name, resource key, and JSON values.
Entity linking
- Copy the command into a text editor.
- Make the following changes in the command where needed:
- Replace the value
<your-language-resource-key>
with your key. - Replace the first part of the request URL
<your-language-resource-endpoint>
with your endpoint URL.
- Replace the value
- Open a command prompt window.
- Paste the command from the text editor into the command prompt window, and then run the command.
curl -i -X POST https://<your-language-resource-endpoint>/language/:analyze-text?api-version=2022-05-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: <your-language-resource-key>" \
-d \
'
{
"kind": "EntityLinking",
"parameters": {
"modelVersion": "latest"
},
"analysisInput":{
"documents":[
{
"id":"1",
"language":"en",
"text": "Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975."
}
]
}
}
'
JSON response
{
"kind": "EntityLinkingResults",
"results": {
"documents": [{
"id": "1",
"entities": [{
"bingId": "a093e9b9-90f5-a3d5-c4b8-5855e1b01f85",
"name": "Microsoft",
"matches": [{
"text": "Microsoft",
"offset": 0,
"length": 9,
"confidenceScore": 0.48
}],
"language": "en",
"id": "Microsoft",
"url": "https://en.wikipedia.org/wiki/Microsoft",
"dataSource": "Wikipedia"
}, {
"bingId": "0d47c987-0042-5576-15e8-97af601614fa",
"name": "Bill Gates",
"matches": [{
"text": "Bill Gates",
"offset": 25,
"length": 10,
"confidenceScore": 0.52
}],
"language": "en",
"id": "Bill Gates",
"url": "https://en.wikipedia.org/wiki/Bill_Gates",
"dataSource": "Wikipedia"
}, {
"bingId": "df2c4376-9923-6a54-893f-2ee5a5badbc7",
"name": "Paul Allen",
"matches": [{
"text": "Paul Allen",
"offset": 40,
"length": 10,
"confidenceScore": 0.54
}],
"language": "en",
"id": "Paul Allen",
"url": "https://en.wikipedia.org/wiki/Paul_Allen",
"dataSource": "Wikipedia"
}, {
"bingId": "52535f87-235e-b513-54fe-c03e4233ac6e",
"name": "April 4",
"matches": [{
"text": "April 4",
"offset": 54,
"length": 7,
"confidenceScore": 0.38
}],
"language": "en",
"id": "April 4",
"url": "https://en.wikipedia.org/wiki/April_4",
"dataSource": "Wikipedia"
}],
"warnings": []
}],
"errors": [],
"modelVersion": "2021-06-01"
}
}
Clean up resources
If you want to clean up and remove an Azure AI services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.