Tutorial: Hyperlinks Management in Excel with Aspose.Cells Cloud API

Introduction

Welcome to this comprehensive tutorial on managing hyperlinks in Excel using Aspose.Cells Cloud API. Hyperlinks are essential elements in Excel spreadsheets that enable users to navigate to other locations within the same workbook, different workbooks, or external resources like websites. Effective hyperlink management can significantly enhance the user experience and functionality of your Excel documents.

In this tutorial, you’ll learn how to programmatically add, retrieve, update, and delete hyperlinks in Excel spreadsheets using Aspose.Cells Cloud API.

Prerequisites

Before starting this tutorial, make sure you have:

An Aspose Cloud account (sign up for a free trial if you don’t have one)
Your Client ID and Client Secret from the Aspose Cloud dashboard
Basic knowledge of REST APIs and HTTP concepts
Familiarity with Excel concepts, especially hyperlinks
A development environment or API testing tool (like Postman, cURL, etc.)
Completed the Worksheets tutorial (recommended but not required)

Tutorial Steps

Step 1: Authentication with Aspose.Cells Cloud API

Before working with hyperlinks, you need to authenticate with the Aspose.Cells Cloud API to get an access token:

curl -v "https://api.aspose.cloud/connect/token" \
-X POST \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json"

Save the access token from the response for use in subsequent API calls.

Step 2: Get All Hyperlinks in a Worksheet

Let’s start by retrieving information about all hyperlinks in an existing worksheet:

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This API returns information about all hyperlinks in the specified worksheet.

Example Response:

{
  "Hyperlinks": {
    "Count": 4,
    "HyperlinkList": [
      {
        "link": {
          "Href": "/0",
          "Rel": "self",
          "Title": null,
          "Type": null
        }
      },
      {
        "link": {
          "Href": "/1",
          "Rel": "self",
          "Title": null,
          "Type": null
        }
      },
      {
        "link": {
          "Href": "/2",
          "Rel": "self",
          "Title": null,
          "Type": null
        }
      },
      {
        "link": {
          "Href": "/3",
          "Rel": "self",
          "Title": null,
          "Type": null
        }
      }
    ],
    "link": null
  },
  "Code": 200,
  "Status": "OK"
}

Step 3: Get Information About a Specific Hyperlink

Now, let’s retrieve detailed information about a specific hyperlink:

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks/0" \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This request retrieves information about the first hyperlink (index 0) in the worksheet.

Example Response:

{
  "Hyperlink": {
    "Address": "https://docs.aspose.cloud/display/cellscloud/Get+Hyperlink+from+Excel+Worksheet",
    "Area": {
      "EndColumn": 0,
      "EndRow": 1,
      "StartColumn": 0,
      "StartRow": 1
    },
    "ScreenTip": null,
    "TextToDisplay": "Aspose.Cells Cloud Documentation",
    "link": {
      "Href": "/test.xlsx/worksheets/Sheet1/hyperlinks/0",
      "Rel": "self",
      "Title": null,
      "Type": null
    }
  },
  "Code": 200,
  "Status": "OK"
}

SDK Example (Python):

# Get hyperlink information example - Tutorial Code Example
import requests
import json

# Authentication
auth_url = "https://api.aspose.cloud/connect/token"
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"

auth_data = {
    "grant_type": "client_credentials",
    "client_id": client_id,
    "client_secret": client_secret
}

auth_headers = {
    "Content-Type": "application/x-www-form-urlencoded",
    "Accept": "application/json"
}

auth_response = requests.post(auth_url, data=auth_data, headers=auth_headers)
access_token = auth_response.json().get("access_token")

# Get hyperlink information
api_url = "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks/0"
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": f"Bearer {access_token}"
}

response = requests.get(api_url, headers=headers)
result = response.json()

# Display hyperlink information
if response.status_code == 200:
    print("Hyperlink information retrieved successfully!")
    
    hyperlink = result.get("Hyperlink", {})
    print("\nHyperlink Details:")
    print(f"Address: {hyperlink.get('Address')}")
    
    area = hyperlink.get('Area', {})
    cell_ref = f"Cell: {chr(65 + area.get('StartColumn'))}{area.get('StartRow') + 1}"
    if area.get('StartColumn') != area.get('EndColumn') or area.get('StartRow') != area.get('EndRow'):
        cell_ref += f" to {chr(65 + area.get('EndColumn'))}{area.get('EndRow') + 1}"
    print(cell_ref)
    
    print(f"Text to display: {hyperlink.get('TextToDisplay')}")
    
    if hyperlink.get('ScreenTip'):
        print(f"ScreenTip: {hyperlink.get('ScreenTip')}")
else:
    print(f"Error: {response.status_code}")
    print(result)

Step 4: Add a Hyperlink to a Worksheet

Now let’s learn how to add a new hyperlink to a worksheet:

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks?firstRow=5&firstColumn=2&totalRows=1&totalColumns=1&address=https://www.aspose.com/" \
-X PUT \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This example adds a hyperlink to cell C6 (row 5, column 2) that points to the Aspose website.

SDK Example (C#):

// Add a hyperlink example - Tutorial Code Example
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Web;

namespace AsposeCellsTutorials
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // Authentication
            var client = new HttpClient();
            var authRequest = new HttpRequestMessage(HttpMethod.Post, "https://api.aspose.cloud/connect/token");
            
            var authContent = new FormUrlEncodedContent(new Dictionary<string, string>
            {
                {"grant_type", "client_credentials"},
                {"client_id", "YOUR_CLIENT_ID"},
                {"client_secret", "YOUR_CLIENT_SECRET"}
            });
            
            authRequest.Content = authContent;
            var authResponse = await client.SendAsync(authRequest);
            var authResult = await authResponse.Content.ReadAsStringAsync();
            
            // Parse access token from JSON response
            // For simplicity, using basic string operations
            var accessToken = authResult.Split("\"access_token\":\"")[1].Split("\"")[0];
            
            // Add a hyperlink
            var apiClient = new HttpClient();
            apiClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            
            // Parameters for the new hyperlink
            var firstRow = 5;
            var firstColumn = 2;
            var totalRows = 1;
            var totalColumns = 1;
            var address = HttpUtility.UrlEncode("https://www.aspose.com/");
            
            var apiUrl = $"https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks?firstRow={firstRow}&firstColumn={firstColumn}&totalRows={totalRows}&totalColumns={totalColumns}&address={address}";
            
            var response = await apiClient.PutAsync(apiUrl, null);
            
            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("Hyperlink added successfully!");
                Console.WriteLine($"A hyperlink to {HttpUtility.UrlDecode(address)} was added to cell C6");
            }
            else
            {
                Console.WriteLine($"Error: {response.StatusCode} - {await response.Content.ReadAsStringAsync()}");
            }
        }
    }
}

Step 5: Update an Existing Hyperlink

You can modify the properties of an existing hyperlink:

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks/0" \
-X POST \
-d "{ \"Hyperlink\": { \"Address\": \"https://www.aspose.cloud/\", \"TextToDisplay\": \"Visit Aspose Cloud\", \"ScreenTip\": \"Click to visit Aspose Cloud\" } }" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This example updates the first hyperlink’s address, display text, and screen tip.

Step 6: Delete a Specific Hyperlink

To remove a specific hyperlink from a worksheet:

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks/0" \
-X DELETE \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This example deletes the first hyperlink (index 0) from the worksheet.

Step 7: Delete All Hyperlinks from a Worksheet

You can also delete all hyperlinks from a worksheet at once:

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks" \
-X DELETE \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This example removes all hyperlinks from the specified worksheet.

SDK Example (Java):

// Delete all hyperlinks example - Tutorial Code Example
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.Scanner;

public class DeleteAllHyperlinksExample {
    public static void main(String[] args) {
        try {
            // Authentication
            String clientId = "YOUR_CLIENT_ID";
            String clientSecret = "YOUR_CLIENT_SECRET";
            String authUrl = "https://api.aspose.cloud/connect/token";
            
            URL url = new URL(authUrl);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
            conn.setRequestProperty("Accept", "application/json");
            conn.setDoOutput(true);
            
            String authData = "grant_type=client_credentials&client_id=" + clientId + "&client_secret=" + clientSecret;
            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = authData.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }
            
            // Read auth response
            Scanner scanner = new Scanner(conn.getInputStream());
            String authResponse = scanner.useDelimiter("\\A").next();
            scanner.close();
            
            // Extract access token (simple approach for demonstration)
            String accessToken = authResponse.split("\"access_token\":\"")[1].split("\"")[0];
            
            // Delete all hyperlinks
            String apiUrl = "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks";
            URL deleteUrl = new URL(apiUrl);
            HttpURLConnection deleteConn = (HttpURLConnection) deleteUrl.openConnection();
            deleteConn.setRequestMethod("DELETE");
            deleteConn.setRequestProperty("Content-Type", "application/json");
            deleteConn.setRequestProperty("Accept", "application/json");
            deleteConn.setRequestProperty("Authorization", "Bearer " + accessToken);
            
            int responseCode = deleteConn.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                System.out.println("All hyperlinks deleted successfully!");
                
                // Read and print the response for educational purposes
                Scanner responseScanner = new Scanner(deleteConn.getInputStream());
                String responseBody = responseScanner.useDelimiter("\\A").next();
                System.out.println("Response: " + responseBody);
                responseScanner.close();
            } else {
                System.out.println("Error: " + responseCode);
                Scanner errorScanner = new Scanner(deleteConn.getErrorStream());
                System.out.println(errorScanner.useDelimiter("\\A").next());
                errorScanner.close();
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Step 8: Creating Different Types of Hyperlinks

Excel supports various types of hyperlinks:

1. URL Hyperlinks

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks?firstRow=1&firstColumn=1&totalRows=1&totalColumns=1&address=https://www.example.com/" \
-X PUT \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

2. Email Hyperlinks

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks?firstRow=2&firstColumn=1&totalRows=1&totalColumns=1&address=mailto:contact@example.com?subject=Hello" \
-X PUT \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

3. Internal Worksheet References

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/hyperlinks?firstRow=3&firstColumn=1&totalRows=1&totalColumns=1&address=Sheet2!A1" \
-X PUT \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

What You’ve Learned

In this tutorial, you’ve learned how to:

Retrieve information about hyperlinks in a worksheet
Add different types of hyperlinks to cells
Update existing hyperlinks’ properties
Delete individual hyperlinks or all hyperlinks from a worksheet
Create different types of hyperlinks (URL, email, internal references)

Troubleshooting Tips

Hyperlink Indices: Hyperlink indices are zero-based and may change if hyperlinks are added or deleted. Always verify the current hyperlinks before performing operations.
URL Encoding: When adding or updating hyperlinks with special characters in the URL, ensure the address is properly URL-encoded.
Valid Addresses: Make sure the hyperlink addresses follow the correct format for their type (URL, email, internal reference).
Cell Ranges: When specifying a range for a hyperlink, ensure the range is valid and doesn’t conflict with existing merged cells.
API Rate Limiting: If you receive 429 (Too Many Requests) responses, you might have exceeded your API quota.

Further Practice

To reinforce your learning, try these exercises:

Create a navigation system using hyperlinks to move between worksheets
Build a contents page with hyperlinks to different sections of a workbook
Implement a batch operation to update multiple hyperlinks at once
Create a document with different types of hyperlinks (URL, email, file, internal)
Build a function to validate and fix broken hyperlinks in a workbook

Next Tutorial

Ready to continue your learning journey? Check out our tutorial on Creating and Managing PivotTables to learn how to work with pivot tables for data analysis and reporting.

Helpful Resources

Feedback

Have questions about this tutorial? Found it helpful? We’d love to hear your feedback! Please share your thoughts and questions in our support forum.