Instructure Developer Documentation Portal
Community
  • Introduction
  • Services
    • Elevate Standards Alignment - AB Connect API
      • Introduction
        • Authentication
        • Addressing Object Properties
        • Requesting Additional Properties in the Response
        • Filtering Using ODATA Like Statements
        • Sorting
        • Facets
        • Paging Data
        • Call Throttling
        • Working with Related Object
        • Error Responses
        • Character Set Support
        • How To Articles, Recommendations and Suggestions
        • Examples
        • Using AB Connect's Embeddable Widgets
      • Reference
        • Standards
        • Standard Collections
        • Events
        • Topics
        • Concepts
        • Assets
        • Asset Definitions
        • Asset Collections
        • Managing and Predicting Relationships
        • Providers
    • Canvas LMS
      • Basics
        • GraphQL
        • API Change Log
        • SIS IDs
        • Pagination
        • Throttling
        • Compound Documents
        • File Uploads
        • API Endpoint Attributes
        • Masquerading
      • OAuth2
        • OAuth2 Overview
        • OAuth2 Endpoints
        • Developer Keys
      • Resources
        • Access Tokens
        • Account Calendars
        • Account Domain Lookups
        • Account Notifications
        • Account Reports
        • Accounts
        • Accounts (LTI)
        • Admins
        • Analytics
        • Announcement External Feeds
        • Announcements
        • API Token Scopes
        • Appointment Groups
        • Assignment Extensions
        • Assignment Groups
        • Assignments
        • Authentication Providers
        • Authentications Log
        • Blackout Dates
        • BlockEditorTemplate
        • Blueprint Courses
        • Bookmarks
        • Brand Configs
        • Calendar Events
        • Collaborations
        • CommMessages
        • Communication Channels
        • Conferences
        • Content Exports
        • Content Migrations
        • Content Security Policy Settings
        • Content Shares
        • Conversations
        • Course Audit log
        • Course Pace
        • Course Quiz Extensions
        • Course Reports
        • Courses
        • Custom Gradebook Columns
        • Developer Key Account Bindings
        • Developer Keys
        • Discussion Topics
        • Enrollment Terms
        • Enrollments
        • ePortfolios
        • ePub Exports
        • Error Reports
        • External Tools
        • Favorites
        • Feature Flags
        • Files
        • Grade Change Log
        • Gradebook History
        • Grading Period Sets
        • Grading Periods
        • Grading Standards
        • Group Categories
        • Groups
        • History
        • InstAccess tokens
        • JWTs
        • Late Policy
        • Learning Object Dates
        • Line Items
        • LiveAssessments
        • Logins
        • LTI Launch Definitions
        • LTI Registrations
        • LTI Resource Links
        • Media Objects
        • Moderated Grading
        • Modules
        • Names and Role
        • New Quiz Items
        • New Quizzes
        • New Quizzes Accommodations
        • New Quizzes Reports
        • Notification Preferences
        • Originality Reports
        • Outcome Groups
        • Outcome Imports
        • Outcome Results
        • Outcomes
        • Pages
        • Peer Reviews
        • Planner
        • Poll Sessions
        • PollChoices
        • Polls
        • PollSubmissions
        • Proficiency Ratings
        • Progress
        • Public JWK
        • Quiz Assignment Overrides
        • Quiz Extensions
        • Quiz IP Filters
        • Quiz Question Groups
        • Quiz Questions
        • Quiz Reports
        • Quiz Statistics
        • Quiz Submission Events
        • Quiz Submission Files
        • Quiz Submission Questions
        • Quiz Submission User List
        • Quiz Submissions
        • Quizzes
        • Result
        • Roles
        • Rubrics
        • Sandboxes
        • Score
        • Search
        • Sections
        • Services
        • Shared Brand Configs
        • SIS Import Errors
        • SIS Imports
        • SIS Integration
        • Smart Search
        • Submission Comments
        • Submissions
        • Tabs
        • Temporary Enrollment Pairings
        • User Observees
        • Users
        • What If Grades
      • Outcomes
        • Outcomes CSV Format
      • Group Categories
        • Group Categories CSV Format
      • SIS
        • SIS CSV Format
      • External Tools
        • LTI
          • Introduction
          • Registration
          • Launch Overview
          • Configuring
          • Variable Substitutions
          • Deep Linking
          • Grading
          • Provisioning
          • PostMessage
          • Platform Notification Service
          • Placements
            • Placements Overview
            • Navigation
            • Homework Submission
            • Editor Button
            • Migration Selection
            • Link Selection (Modules)
            • Assignment Selection
            • Collaborations
        • xAPI
        • Canvas Roles
        • Plagiarism Detection Platform
          • Overview
          • Plagiarism Detection Platform Assignments
          • Plagiarism Detection Platform Users
          • Plagiarism Detection Submissions
          • Webhooks Subscriptions for Plagiarism Platform
          • JWT Access Tokens
      • Data Services
        • Live Events
          • Overview
            • Introduction
            • Setup
            • Caliper
            • Metadata
          • Event Format
            • Canvas
              • Account
              • Asset
              • Assignment
              • Attachment
              • Content
              • Conversation
              • Course
              • Discussion
              • Enrollment
              • Grade
              • Group
              • Learning
              • Logged
              • Module
              • Outcome
              • Outcomes
              • Plagiarism
              • Quiz
              • Rubric
              • Sis
              • Submission
              • Syllabus
              • User
              • Wiki
            • Caliper IMS 1.1
              • Assessment
              • Basic
              • Forum
              • Grading
              • Navigation Events
              • Session
    • Catalog
      • APIs
        • Analytics
        • Bulk Enrollments
        • Catalogs
        • Certificates
        • Completed Certificates
        • Courses
        • Email Domain Set
        • Enrollments
        • Orders
        • Programs
        • Progresses
        • Tags
        • User Registrations
        • Users
        • Waitlist Applicants
    • Credentials
      • Getting Started
      • Authentication
        • Password-Based Authentication
        • Authorization Code-Based Authentication
      • Pagination
      • APIs
        • Assertions
        • Backpack
        • Badgeclasses
        • Issuers
        • Organizations
        • Users
      • Release Notes
    • Data Access Platform
      • Key Concepts
      • Data Formats
      • Rate Limits & Policies
      • Datasets
        • Namespaces
          • canvas
            • canvas types
          • canvas_logs
          • catalog
        • Additional Notes
        • Entity Relationship Diagram
      • Query API
        • Authentication
        • Reference
      • Command Line (DAP CLI)
        • Getting Started
        • Secure Connection
        • Reference
          • dap snapshot
          • dap incremental
          • dap list
          • dap schema
          • dap initdb
          • dap syncdb
          • dap dropdb
      • Client Library
        • Examples
        • Reference
      • Release Notes
      • Status
    • DataSync
      • Interop API
      • Interop Data API
      • Grades Exchange API
      • OneRoster API
      • Platform API
    • Instructure Media
      • API Reference
        • Captions
        • Collection
        • Courses
        • Group
        • Insights
        • Media
        • Media Upload
        • Ping
        • Professional Captioning
        • Tags
        • Transfer Media
        • User
    • Quizzes
      • Quiz API
Powered by GitBook

Copyright © 2008-2024 Instructure, Inc. All rights reserved. Various trademarks held by their respective owners.

On this page
  • 1. Get API Client ID and Secret
  • 2. Install DAP CLI on Your Computer
  • 3. Store Client Credentials in Environment Variables
  • 4. Work with Databases
  • Store Connection String in Environment Variables
  • Obtain Full Snapshots of Tables
  • Synchronize Data of Tables
  • Changing the Temporary Storage Location
  • 5. Export Data
  • Snapshot Export
  • Incremental Export

Was this helpful?

  1. Services
  2. Data Access Platform
  3. Command Line (DAP CLI)

Getting Started

A step-by-step guide for IT admins, analysts, and non-technical users.

PreviousCommand Line (DAP CLI)NextSecure Connection

Last updated 2 months ago

Was this helpful?

1. Get API Client ID and Secret

To access the DAP API, you will need a Client ID and Secret. These are generated via the Instructure Identity Services.

Steps:

  1. Log into .

  2. Select your institution from the drop-down menu and log in.

  3. Once authorized, navigate to the dashboard and click Add New Key.

  4. Enter a name for the key and set the expiration time.

  5. Copy the Client ID and Secret when they appear. Note: These are displayed only once. If you lose them, you will need to generate new ones.

2. Install DAP CLI on Your Computer

The DAP CLI tool allows you to interact with the Canvas Data 2 API. Installation steps differ slightly depending on your operating system.

For Mac:

  1. Install Xcode Developer Tools:

    xcode-select --install
  2. download and install Python 3.10+ from :

    python3 --version
  3. Install PIP (if not installed by default):

    pip3 --version
  4. Install the DAP CLI tool with PostgreSQL support:

    pip3 install "instructure-dap-client[postgresql]"

For Windows:

  1. Install the DAP CLI tool using the Windows command prompt:

    pip3 install "instructure-dap-client[postgresql]"

If you miss installing an extra feature, the library will not be able to synchronize data with a database, and you may get an error message similar to the following:

```
ERROR - missing dependency: `asyncpg`; you may need to run `pip install pysqlsync[postgresql]`
```

3. Store Client Credentials in Environment Variables

For secure access to the API, it's recommended to store your credentials as environment variables. This prevents sensitive information from being exposed in command-line arguments.

MacOS/Linux:

  1. Open Terminal and run the following commands, replacing placeholders with your actual Client ID and Secret:

    export DAP_API_URL='https://api-gateway.instructure.com'
    export DAP_CLIENT_ID='your_canvas_data_client_id'
    export DAP_CLIENT_SECRET='your_canvas_data_secret'
  2. Restart Terminal for changes to take effect.

Windows:

set DAP_API_URL=https://api-gateway.instructure.com
set DAP_CLIENT_ID=your_canvas_data_client_id
set DAP_CLIENT_SECRET=your_canvas_data_secret

Unless you set environment variables, you need to pass endpoint URL, Client ID, and Secret to the dap command explicitly:

dap --base-url https://api-gateway.instructure.com --client-id=us-east-1#0c59cade-...-2ac120002 --client-secret=xdEC0lI...4X4QBOhM incremental --namespace canvas --table accounts --since 2022-07-13T09:30:00+02:00

4. Work with Databases

DAP CLI allows you to interact with PostgreSQL, MySQL or MSSQL databases. You will need the connection string of your database for DAP to function correctly.

Connection String Format:

protocol://username:password@host:port/database_name

Examples:

postgresql://user:password@host:5432/mydatabase
mysql://user:password@host:3306/mydatabase
mssql://user:password@host:1433/mydatabase

Store Connection String in Environment Variables

MacOS/Linux:

  1. Open Terminal and run the following commands, replacing placeholders with your actual Client ID and Secret:

    export DAP_CONNECTION_STRING=postgresql://user:password@localhost:5432/mydatabase
  2. Restart Terminal for changes to take effect.

Windows:

set DAP_CONNECTION_STRING=postgresql://user:password@localhost:5432/mydatabase

Obtain Full Snapshots of Tables

Command:

dap initdb --connection-string postgresql://user:password@localhost/mydb --namespace canvas --table accounts,users

Regular use of snapshots is not recommended, as they are resource-intensive for the API and costly to process on the client side.

Synchronize Data of Tables

Command:

dap syncdb --connection-string postgresql://user:password@localhost/mydb --namespace canvas --table accounts,users

Changing the Temporary Storage Location

If you need to change the temporary storage directory for data processing, you can configure the location using the following command-line option:

dap syncdb --temp-dir /new/temp/location --connection-string postgresql://user:password@localhost/mydb --namespace canvas --table accounts,users

5. Export Data

You can export data using either the snapshot or incremental methods, depending on your use case.

Snapshot Export

Command:

dap snapshot --namespace canvas --table accounts

Regular use of snapshots is not recommended, as they are resource-intensive for the API and costly to process on the client side.

Incremental Export

Command:

dap incremental --namespace canvas --table accounts --since YYYY-MM-DDTHH:MM:SSZ

Install Python 3.10+ from .

Follow this or use the set command in the Windows command line:

Follow this or use the set command in the Windows command line:

Use the command to download full snapshots of tables and store them in your database.

After obtaining snapshots, keep your database updated with the command. This ensures incremental changes are applied to your tables.

Use command to download a full copy of tables at a point in time.

The commands captures only the data that has changed since your last export.

Instructure Identity Services
here
here
guide to setting environment variables
guide to setting environment variables
dap initdb
dap syncdb
dap snapshot
dap incremental