印象笔记 API 中常见的术语和概念
Access - Basic
Evernote Cloud API keys with Basic Access can list the Notebooks, Tags and Saved Searches stored in a user's account as well as create new Notes. Basic Access does not permit the reading or modification of existing Notes (this requires Full Access).
Access - Full
Evernote Cloud API keys with Full Access perform the same actions as a key with Basic Access as well as read and modify the Notes in a user's account.
Accounting Data Structure
A data structure defined in the Evernote API that contains accounting-related information about a user's account (whether they are a Premium user, their current upload limit, etc.).
"API" is short for "Application Programming Interface" and refers to the way software and services communicate with one another. Third-party applications that integrate with Evernote do so using Evernote's API.
A scripting language that ships with Mac OS X which allows users to programmatically interact with applications and the OS itself. Evernote for Mac includes an AppleScript dictionary which exposes several application functions to AppleScript applications.
This error code is returned by the Evernote API when the auth token used to make a request has expired. For more information on refreshing an auth token, see [page].
Describes the process by which a user or application verifies its identity with the Evernote service. Users do this by providing a valid username and password, while applications authenticate using a modern protocol called OAuth.
A notebook created in an Evernote Business account. This notebook can be created by either a Business uer or administrator, but the notebook and its contents are the property of the business.
An instance of the
NoteStore type that allows authenticated users to browse and create notes and notebooks using their Evernote Business account.
Any application that interacts with the Evernote service is a client, including all of the official applications. This term describes one half of the "client/server" paradigm implemented in many modern software systems.
Evernote's Cloud API allows applications and services to interact with its users' Evernote accounts. All communication takes place over the Internet between the client and the Evernote Cloud API.
A member of the Notes.attributes structure that, if set, indicates that the body of the note follows a specific structure and is not editable using Evernote client applications. Example contentClass values include
evernote.hello.encounter; these notes are only editable in their respective applications (Evernote Food and Evernote Hello).
A commonly used function exposed in the Evernote Cloud API that allows client applications to create Notes in an Evernote user's account.
Used when developing an Evernote-aware application, a Developer Token can be used in place of the authentication token described in the API documentation. It allows the developer to begin interacting with the Evernote Cloud API without having to fully implement the OAuth authentication protocol first. Developer Tokens are associated with a single Evernote user account and cannot be used in production applications. Get your own developer token here.
Short for "Evernote Data Access and Management", this term refers to the protocol used when exchanging Evernote data with the Evernote service.
This exception is thrown by EDAM procedures when a caller asks to perform an operation that does not exist.
EDAMSync, Full Sync
Refers to the process by which a user's account is synchronized completely to a client application (e.g., Evernote for Mac). The specification for EDAMSync can be found here.
This exception is thrown by EDAM procedures when a call fails as a result of an a problem in the service that could not be changed through user action.
This exception is thrown by EDAM procedures when a call fails as a result of a problem that a user may be able to resolve. For example, if the user attempts to add a note to their account which would exceed their storage quota, this type of exception may be thrown to indicate the source of the error so that they can choose an alternate action.
An ENML node type that describes a textual portion of a note that has been encrypted by the user.
The top-level element for all ENML documents. It replaces the andtags found in XHTML documents.
An ENML node type that describes a checkbox (including it's checked/unchecked state).
A markup language based on XHTML, ENML is used by Evernote to represent the layout and content of notes. It is formally defined in the ENML Document Type Definition (DTD). Clients that create or modify notes will be required to strictly adhere to this standard.
A separate Evernote product for use in businesses. A normal Evernote user account can be associated with a single Evernote Business where the user can create new Business notebooks and notes.
Evernote Search Grammar
This document describes the various operators and advanced capabilities implemented in Evernote's search functionality. It also defines the formal grammar expressed in EBNF notation.
Evernote URLs (evernote://)
This custom URL scheme allows Evernote to handle incoming requests made from other applications. For example, it is used when building Note Links which, when clicked, will give control to the local Evernote application and immediately load the note in question.
A common Cloud API function that allows applications to search a user's account using criteria defined in a companion NoteFilter object.
Github is a socially-focused developer Web site that allows users to store and share both public and private projects using the Git revision control system. All of Evernote's SDKs are available on Evernote's Github page.
Short for "Globally Unique Identifier", a GUID is an alphanumeric ID assigned to Notes, Notebooks, Tags and Saved Searches within Evernote's database.
Evernote's Image Processing technology indexes every image a user stores in their account and attempts to make any text visible in a given image (street signs, photos of handwritten text, etc.) searchable. This process, commonly known as Optical Character Recognition (or OCR).
Third-part developers working with the Evernote Cloud API are each issued an API key. Initially, this key allows the application to connect and interface with our Sandbox development server. When the developer deems the application ready for production use, the API key associated with that application must be configured on our production servers. This process is called "key activation". Complete this form to request activation for your API key.
An error code is returned if a given API operation causes a limit set on the user's account (other than their monthly upload quota) to be exceeded.
Linked Notebooks are shared Notebooks created by a different user that have been added to a given user's account. These Notebooks can either be public or shared with one or more individual users.
Three of our applications—Evernote for Mac, Windows and Android—support interactions from other local applications using this API (which is different from the Cloud API). Evernote for Mac offers a robust AppleScript dictionary, Evernote for Windows offers the
enclient.exe command line utility and Evernote for Android exposes several pieces of functionality using the Intents technology that ships with modern versions of Android.
Lucene is an Apache Foundation project that provides high-performance search capabilities for text. A separate Lucene index is maintained for each user account and includes Note data and metadata as well as Image Recognition data. Lucene is the foundation of Evernote's search functionality.
MD5 Checksum (or MD5 Hash)
MD5 is a cryptographic hash function. When run against a file or other input, it will generate a 16-byte checksum value that can be used to verify the integrity of the input. For example, it's common for software vendors to include the MD5 checksum of a digital file made available for download. Comparing the provided checksum with one generated after download can ensure that the file wasn\t modified or corrupted in transit.
Originally developed as a standard for classifing types of files and data included in email messages, MIME ("Multipurpose Internet Mail Extensions") content types are a employed all over the web to identify the format of binary files, character encodings, and others. Each MIME type consists of a type and a subtype (e.g., a PNG image would have a type of
image and a subtype of
png, resulting in a MIME type of
image/png). A small subset of MIME types are available for use with the
resource: search operator in Evernote.
A single unit of information stored in Evernote. Everthing stored in an Evernote account will be stored in a Note.
Each note includes several pieces of metadata about that note: date it was created and last modified, location information, source URL, etc. These values are collectively called "Note Attributes".
A hyperlink generated by Evernote by which a user can link directly to a note in his/her account. These links rely on the
evernote:// URL scheme and will work in any application on the user's desktop or mobile device. Note Links are different from Shared Note URLs, which allow users to share individual notes with others via the web.
A named container for Notes that can be synchronized with the Evernote service (if the "Synchronized" Notebook type is chosen) or live solely on the computer where the Notebook is created (if the "Local" Notebook type is chosen — an option currently available only on Desktop clients). Notebooks can be shared with individuals or made public. Each user account is limited to 250 total notebooks.
Notebook Stacks give users an additional level of organization for their Notebooks. Notebook Stacks visually hold groups of Notebooks so the user can organize their notebooks by topic (or however they see fit). It's important to note that, in terms of data, Notebook Stacks have no meaningful relationship to their contained Notebooks; they are simply a visual aid for users and do not translate to a "parent/child" relationship.
A data type defined in the Evernote Cloud API that, when included with a call to
findNotes, indicates which Notes the service should return. Some members of this type include the GUID for a Notebook, a series of GUIDs for one or more tags and a textual search query. Read more about this type in the NoteFilter section of our API reference.
This service implements all API functions dealing with accessing and modifying the data stored in a user's Evernote account including Notes, Notebooks, Tags, Saved Searches and others. Read more in the NoteStore section of our API reference.
OAuth is an authentication protocol which allows users to authorize a third-party application or service to interact with a second-party service (like Evernote) without exposing the user's credentials to the third-party app or service. More plainly, when somebody using a third-party application wants to connect that application to Evernote, the user is taken to an Evernote web page where they authorize the third-party application. After successful authorization, the application is given an Auth Token which it will use when interacting with the Evernote Cloud API. Visit this page for a more thorough explanation of OAuth.
Short for "Optical Character Recognition", this term describes the capability of a system or service to identify text from within visual media (like photos and other images).
These identifiers are used when a user nests one tag within another; the nested tag is assigned a ParentGUID (which belongs to the tag in which the nested tag now appears).
Part of the
EDAMErrorCode enumeration defined in the Evernote Cloud API, this error indicates that the action requested is not authorized to the API key used to make the request.
Refers to a set of technologies required to run a system or service (e.g., the Evernote for Mac application requires the OS X platform to operate).
The process by which a client application or service makes periodic requests to a server, often to check for updated user data or service components.
The "live" environment where stable software or services operate. For Evernote specifically, services are developed and tested using our Sandbox environment and, once deemed stable enough for public or widespread use, subsequently deployed to Production.
The amount of data an Evernote account is permitted to upload per month. Free accounts may upload 60mb of data per month while Premium accounts are allowed 1gb of uploaded data per month. This quota is reset each month on the date the user's account was created (or upgraded, for Premium accounts). Premium users also have the option to purchase individual upload allowance increases.
This error code indicates that user has reached their monthly bandwidth allotment according to their account type (Free or Premium) and is unable to add more data to their account before their monthly quota is reset or they choose to purchase a one-time upload allowance increase (available to Premium users only).
Notes created using applications other than Evernote proper have the option to mark such notes as read-only in other applications. These notes often contain specific formatting information or metadata included by the application that created the note (and which could degrade user experience if modified outside said application). Two examples of this behavior are Evernote Food and Evernote Hello; notes created by these applications are read-only in all other Evernote client applications.
A custom XML format used to describe the recognition information collected during Evernote's Image Processing. This information is embedded in the body of the note after processing and sent to client applications to facilitate search.
Refers to any non-textual data stored in an Evernote Note including images, audio clips, PDF documents and other files.
Evernote's development service; an exact duplicate of the Production service made available to developers who are building third-party integrations with Evernote and need a place to test their software using real data (but not actual user accounts). You can visit the Evernote Sandbox here.
A normal Evernote user account that is created on Evernote's developer Sandbox.
An easy way for Evernote users to repeatedly execute the same search (and give it a custom name). Saved Searches can be created using any Evernote client and are synchronized to all other devices.
Short for "Software Development Kit", this term describes a collection of vendor-supplied source files and software libraries that enables developers to easily integrate or interact with the vendor's software or service. SDKs can also include sample applications, documentation and other resources created by the vendor to aid the third-party developer.
Shard, Shard ID
A "shard" in the context of Evernote describes a set of servers housed in the Evernote data center that both stores user data and powers the Evernote service. Each Evernote account is assigned to a specific shard and a user's shard ID is a required parameter for some Evernote Cloud API functions.
A notebook whose contents have been shared with either a specific group of individuals or the entire world.
Most Evernote clients support the ability to share individual notes via URL, email and social networks.
An online community where programmers can ask and answer questions related to software development. You can view Stack Overflow questions tagged with "Evernote" here.
Short, textual labels applied to Notes in Evernote. Tags are synced to the Evernote service and available to the user on all client applications they use.
An Apache Software Foundation project, Thrift allows vendors to define data types and service interfaces in a text file. This file is then used to generate client and server code (among other things) in multiple programming languages. The Evernote Cloud API and SDKs are implemented using Thrift.
Smaller representations of images and other data. Thumbnails are used in a variety of contexts across Evernote's client applications. Read more about thumbnails and how to use them here.
The Evernote Trunk is a curated collection of hardware, software, services and products that integrate with or relate to Evernote. Visit the Evernote Trunk here.
Update Sequence Number (USN)
Used in the Evernote sync process, the USN is incremented each time a user's account is updated. When a client application syncs, this value determines the number of updates it needs to download to be fully in sync with the Evernote service.
A service provided by the Evernote Cloud API whose primary role is authenticating users. It can also be used to get additional user information (username, Premium account status, etc.). Read more in the UserStore section of our API reference.
Third-party applications can register for web-based notifications when an authorized user creates or update a Note in their account. These notifications are sent as HTTP GET requests and include the user's User ID, the GUID of the Note in question and the reason for the notification (
update). Optionally, Webhooks can be configured to use a NoteFilter so that only changes to Notes matching certain criteria will trigger the notification. Read more about Webhooks here.
Evernote's Local API includes the ability to interact directly with Evernote for Windows using the Command Line Interface ("CLI", also known as the Command Prompt) using two executables:
enscript.exe. You can read about the specific usage of these commands on the Windows section of the Local API documentation.