Lua

Download a File from a SharePoint Documents Library

See more SharePoint Examples

This example shows how to use Chilkat's HttpCurl class to download a file from the root of a SharePoint Documents document library. The example demonstrates how HttpCurl automatically resolves the SharePoint site name to a site ID, finds the drive ID for the Documents library, locates the file by name, and then downloads the file content using Microsoft Graph.

Lua

local chilkat = require("chilkat")

-- This example downloads a file named "hamlet.json" from the root of the SharePoint
-- Documents document library.
--
-- The example demonstrates how HttpCurl can automatically resolve all of the
-- information needed to locate and download a file:
--
--   site_name            -> site_id
--   site_id              -> document_library_id
--   document_library_id  -> file_id
--   file_id              -> file content
--
-- The application only provides the SharePoint site name and the desired
-- filename.  HttpCurl automatically executes the required Microsoft Graph
-- requests to obtain the remaining values.

local success = false

-- --------------------------------------------------------------------------------------------------------
-- Before running this example, create an Azure App Registration and grant it
-- the Microsoft Graph permissions required to access SharePoint.
--
-- The application will authenticate using OAuth2 Client Credentials.
-- See:
-- How to Create SharePoint App Registration for OAuth 2.0 Client Credentials
-- --------------------------------------------------------------------------------------------------------

-- Build a JSON authentication configuration.
-- HttpCurl will use this information to automatically obtain OAuth2 access tokens.
local jsonAuth = chilkat.JsonObject.new()

-- Enable secret lookup.
--
-- Instead of hard-coding sensitive values such as the client ID,
-- client secret, and token endpoint, secret specification strings
-- are used.  Chilkat automatically retrieves the actual values from
-- Windows Credential Manager (Windows) or Apple Keychain (macOS).
--
-- See:
-- Secret Specification Strings
jsonAuth.enable_secrets = true

success = jsonAuth:update_string("oauth2.client_id", "!!sharepoint|oauth2|client_id")
if success then
    success = jsonAuth:update_string("oauth2.client_secret", "!!sharepoint|oauth2|client_secret")
end

if success then
    success = jsonAuth:update_string("oauth2.token_endpoint", "!!sharepoint|oauth2|token_endpoint")
end

if not success then
    print(jsonAuth.last_error_text)
    return
end

-- Request Microsoft Graph permissions that were granted to the application.
jsonAuth:update_string("oauth2.scope", "https://graph.microsoft.com/.default")

-- ---------------------------------------------------------------------------------------------------

local curl = chilkat.HttpCurl.new()

-- Associate the OAuth2 configuration with HttpCurl.
--
-- When the request is executed, Chilkat automatically obtains an access token
-- if needed and adds the Authorization: Bearer header to the HTTP request.
curl:set_auth(jsonAuth)

-- Define values that are already known.
--
-- These variables are referenced in curl commands using
-- {{variable_name}} substitution syntax.
curl:set_var("sharepoint_hostname", "example.sharepoint.com")
curl:set_var("site_name", "test")

-- The first step is to obtain the Microsoft Graph site ID.
--
-- The application only knows the SharePoint site name, so define
-- a function that can retrieve the site information.
curl:add_function("getSite", "GET https://graph.microsoft.com/v1.0/sites/root:/sites/{{site_name}}")

-- Extract the site's ID and store it in the HttpCurl variable named site_id.
curl:add_output("getSite", "id", "site_id")

-- The next step is to find the Documents document library.
--
-- Microsoft Graph refers to document libraries as "drives".
curl:add_function("getDrives", "GET https://graph.microsoft.com/v1.0/sites/{{site_id}}/drives")

-- Search the returned drives for the one named "Documents"
-- and save its drive ID in the document_library_id variable.
curl:add_output2("getDrives", "value", "name", "Documents", true, "id", "document_library_id")

-- Now list the contents of the Documents document library.
curl:add_function("getFiles", "GET https://graph.microsoft.com/v1.0/sites/{{site_id}}/drives/{{document_library_id}}/root/children")

-- Search the returned files for an item named "hamlet.json"
-- and save its Microsoft Graph item ID in the file_id variable.
curl:add_output2("getFiles", "value", "name", "hamlet.json", true, "id", "file_id")

-- This is the target request.
--
-- GET -L https://graph.microsoft.com/v1.0/drives/{{document_library_id}}/items/{{file_id}}/content
--
-- The /content endpoint returns the actual contents of the file.
--
-- The -L option instructs HttpCurl to follow the redirect returned by
-- Microsoft Graph.  The Graph API typically responds with a redirect
-- to the actual file download URL.
local curlCommand = "GET -L https://graph.microsoft.com/v1.0/drives/{{document_library_id}}/items/{{file_id}}/content"

-- Execute the request.
--
-- HttpCurl examines the target request and determines that both
-- document_library_id and file_id are required.
--
-- To obtain these values, it automatically builds and executes
-- the following dependency chain:
--
--   1) getSite      -> site_id
--   2) getDrives    -> document_library_id
--   3) getFiles     -> file_id
--   4) download     -> file content
--
-- The final response returned by DoYourThing is the downloaded
-- file content from the target request.
success = curl:do_your_thing(curlCommand)
if not success then
    print(curl.last_error_text)
    return
end

-- A successful Graph response should return HTTP 200.
-- Any other status code typically indicates an authentication,
-- permission, site lookup, document library lookup, or file lookup error.
local statusCode = curl.status_code
if statusCode ~= 200 then
    print(curl.response_body_str)
    print("status code = " .. statusCode)
    return
end

-- The response body contains the contents of the downloaded file.
local sbFileContents = chilkat.StringBuilder.new()
curl:get_response_sb(sbFileContents)

-- Optionally save the downloaded content to a local file.
--
-- The third argument controls whether the file is appended.
-- Passing ckfalse causes the file to be overwritten if it already exists.
success = sbFileContents:write_file("c:/temp/hamlet.json", "utf-8", false)
if not success then
    print(sbFileContents.last_error_text)
    return
end

print("Success.")