Update README
This commit is contained in:
parent
ed324caf16
commit
1db646c13e
52
README.md
52
README.md
@ -9,10 +9,10 @@ Collection = "ProjectsActive"
|
|||||||
|
|
||||||
# Anki-Connect
|
# Anki-Connect
|
||||||
|
|
||||||
AnkiConnect enables external applications such as [Yomichan](https://foosoft.net/projects/yomichan/) to communicate with
|
Anki-Connect enables external applications such as [Yomichan](https://foosoft.net/projects/yomichan/) to communicate
|
||||||
[Anki](https://apps.ankiweb.net/) over a simple HTTP API. Its capabilities include executing queries against the user's
|
with [Anki](https://apps.ankiweb.net/) over a simple HTTP API. Its capabilities include executing queries against the
|
||||||
card deck, automatically creating new cards, and more. AnkiConnect is compatible with the latest stable (2.1.x) releases
|
user's card deck, automatically creating new cards, and more. Anki-Connect is compatible with the latest stable (2.1.x)
|
||||||
of Anki; older versions (2.0.x and below) are no longer supported.
|
releases of Anki; older versions (2.0.x and below) are no longer supported.
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
@ -20,15 +20,15 @@ The installation process is similar to other Anki plugins and can be accomplishe
|
|||||||
|
|
||||||
1. Open the `Install Add-on` dialog by selecting `Tools` | `Add-ons` | `Get Add-ons...` in Anki.
|
1. Open the `Install Add-on` dialog by selecting `Tools` | `Add-ons` | `Get Add-ons...` in Anki.
|
||||||
2. Input [2055492159](https://ankiweb.net/shared/info/2055492159) into the text box labeled `Code` and press the `OK` button to proceed.
|
2. Input [2055492159](https://ankiweb.net/shared/info/2055492159) into the text box labeled `Code` and press the `OK` button to proceed.
|
||||||
3. Restart Anki when prompted to do so in order to complete the installation of AnkiConnect.
|
3. Restart Anki when prompted to do so in order to complete the installation of Anki-Connect.
|
||||||
|
|
||||||
Anki must be kept running in the background in order for other applications to be able to use AnkiConnect. You can
|
Anki must be kept running in the background in order for other applications to be able to use Anki-Connect. You can
|
||||||
verify that AnkiConnect is running at any time by accessing `localhost:8765` in your browser. If the server is running,
|
verify that Anki-Connect is running at any time by accessing `localhost:8765` in your browser. If the server is running,
|
||||||
you will see the message `AnkiConnect` displayed in your browser window.
|
you will see the message `Anki-Connect` displayed in your browser window.
|
||||||
|
|
||||||
### Notes for Windows Users
|
### Notes for Windows Users
|
||||||
|
|
||||||
Windows users may see a firewall nag dialog box appear on Anki startup. This occurs because AnkiConnect runs a local
|
Windows users may see a firewall nag dialog box appear on Anki startup. This occurs because Anki-Connect runs a local
|
||||||
HTTP server in order to enable other applications to connect to it. The host application, Anki, must be unblocked for
|
HTTP server in order to enable other applications to connect to it. The host application, Anki, must be unblocked for
|
||||||
this plugin to function correctly.
|
this plugin to function correctly.
|
||||||
|
|
||||||
@ -36,7 +36,7 @@ this plugin to function correctly.
|
|||||||
|
|
||||||
Starting with [Mac OS X Mavericks](https://en.wikipedia.org/wiki/OS_X_Mavericks), a feature named *App Nap* has been
|
Starting with [Mac OS X Mavericks](https://en.wikipedia.org/wiki/OS_X_Mavericks), a feature named *App Nap* has been
|
||||||
introduced to the operating system. This feature causes certain applications which are open (but not visible) to be
|
introduced to the operating system. This feature causes certain applications which are open (but not visible) to be
|
||||||
placed in a suspended state. As this behavior causes AnkiConnect to stop working while you have another window in the
|
placed in a suspended state. As this behavior causes Anki-Connect to stop working while you have another window in the
|
||||||
foreground, App Nap should be disabled for Anki:
|
foreground, App Nap should be disabled for Anki:
|
||||||
|
|
||||||
1. Start the Terminal application.
|
1. Start the Terminal application.
|
||||||
@ -50,11 +50,11 @@ foreground, App Nap should be disabled for Anki:
|
|||||||
|
|
||||||
## Application Interface for Developers
|
## Application Interface for Developers
|
||||||
|
|
||||||
AnkiConnect exposes internal Anki features to external applications via an easy to use API. After being installed, this
|
Anki-Connect exposes internal Anki features to external applications via an easy to use API. After being installed, this
|
||||||
plugin will start an HTTP server on port 8765 whenever Anki is launched. Other applications (including browser
|
plugin will start an HTTP server on port 8765 whenever Anki is launched. Other applications (including browser
|
||||||
extensions) can then communicate with it via HTTP requests.
|
extensions) can then communicate with it via HTTP requests.
|
||||||
|
|
||||||
By default, AnkiConnect will only bind the HTTP server to the `127.0.0.1` IP address, so that you will only be able to
|
By default, Anki-Connect will only bind the HTTP server to the `127.0.0.1` IP address, so that you will only be able to
|
||||||
access it from the same host on which it is running. If you need to access it over a network, you can set the
|
access it from the same host on which it is running. If you need to access it over a network, you can set the
|
||||||
environment variable `ANKICONNECT_BIND_ADDRESS` to change the binding address. For example, you can set it to `0.0.0.0`
|
environment variable `ANKICONNECT_BIND_ADDRESS` to change the binding address. For example, you can set it to `0.0.0.0`
|
||||||
in order to bind it to all network interfaces on your host.
|
in order to bind it to all network interfaces on your host.
|
||||||
@ -62,10 +62,10 @@ in order to bind it to all network interfaces on your host.
|
|||||||
### Sample Invocation
|
### Sample Invocation
|
||||||
|
|
||||||
Every request consists of a JSON-encoded object containing an `action`, a `version`, contextual `params`, and a `key`
|
Every request consists of a JSON-encoded object containing an `action`, a `version`, contextual `params`, and a `key`
|
||||||
value used for authentication (which is optional and can be omitted by default). AnkiConnect will respond with an object
|
value used for authentication (which is optional and can be omitted by default). Anki-Connect will respond with an
|
||||||
containing two fields: `result` and `error`. The `result` field contains the return value of the executed API, and the
|
object containing two fields: `result` and `error`. The `result` field contains the return value of the executed API,
|
||||||
`error` field is a description of any exception thrown during API execution (the value `null` is used if execution
|
and the `error` field is a description of any exception thrown during API execution (the value `null` is used if
|
||||||
completed successfully).
|
execution completed successfully).
|
||||||
|
|
||||||
*Sample successful response*:
|
*Sample successful response*:
|
||||||
```json
|
```json
|
||||||
@ -80,11 +80,11 @@ completed successfully).
|
|||||||
{"result": null, "error": "guiBrowse() got an unexpected keyword argument 'foobar'"}
|
{"result": null, "error": "guiBrowse() got an unexpected keyword argument 'foobar'"}
|
||||||
```
|
```
|
||||||
|
|
||||||
For compatibility with clients designed to work with older versions of AnkiConnect, failing to provide a `version` field
|
For compatibility with clients designed to work with older versions of Anki-Connect, failing to provide a `version`
|
||||||
in the request will make the version default to 4. Furthermore, when the provided version is level 4 or below, the API
|
field in the request will make the version default to 4. Furthermore, when the provided version is level 4 or below, the
|
||||||
response will only contain the value of the `result`; no `error` field is available for error handling.
|
API response will only contain the value of the `result`; no `error` field is available for error handling.
|
||||||
|
|
||||||
You can use whatever language or tool you like to issue request to AnkiConnect, but a couple of simple examples are
|
You can use whatever language or tool you like to issue request to Anki-Connect, but a couple of simple examples are
|
||||||
included below as reference.
|
included below as reference.
|
||||||
|
|
||||||
#### Curl
|
#### Curl
|
||||||
@ -160,9 +160,9 @@ console.log(`got list of decks: ${result}`);
|
|||||||
|
|
||||||
### Hey, could you add a new action to support $FEATURE?
|
### Hey, could you add a new action to support $FEATURE?
|
||||||
|
|
||||||
The primary goal for AnkiConnect was to support real-time flash card creation from the
|
The primary goal for Anki-Connect was to support real-time flash card creation from the
|
||||||
[Yomichan](https://foosoft.net/projects/yomichan/) browser extension. The current API provides all the required actions
|
[Yomichan](https://foosoft.net/projects/yomichan/) browser extension. The current API provides all the required actions
|
||||||
to make this happen. I recognise that the role of AnkiConnect has evolved from this original vision, and I am happy to
|
to make this happen. I recognise that the role of Anki-Connect has evolved from this original vision, and I am happy to
|
||||||
review new feature requests.
|
review new feature requests.
|
||||||
|
|
||||||
With that said, *this project operates on a self-serve model*. If you would like a new feature, create a PR. I'll review
|
With that said, *this project operates on a self-serve model*. If you would like a new feature, create a PR. I'll review
|
||||||
@ -1480,9 +1480,9 @@ corresponding to when the API was available for use.
|
|||||||
the request isn't in the `webCorsOriginList` list. It also doesn't require the api key. Calling this method will
|
the request isn't in the `webCorsOriginList` list. It also doesn't require the api key. Calling this method will
|
||||||
not display the popup if the origin is already trusted.
|
not display the popup if the origin is already trusted.
|
||||||
|
|
||||||
This should be the first call you make to make sure that your application and AnkiConnect are able to communicate
|
This should be the first call you make to make sure that your application and Anki-Connect are able to communicate
|
||||||
properly with each other. New versions of AnkiConnect are backwards compatible; as long as you are using actions
|
properly with each other. New versions of Anki-Connect are backwards compatible; as long as you are using actions
|
||||||
which are available in the reported AnkiConnect version or earlier, everything should work fine.
|
which are available in the reported Anki-Connect version or earlier, everything should work fine.
|
||||||
|
|
||||||
*Sample request*:
|
*Sample request*:
|
||||||
```json
|
```json
|
||||||
@ -2044,7 +2044,7 @@ corresponding to when the API was available for use.
|
|||||||
Creates a note using the given deck and model, with the provided field values and tags. Returns the identifier of
|
Creates a note using the given deck and model, with the provided field values and tags. Returns the identifier of
|
||||||
the created note created on success, and `null` on failure.
|
the created note created on success, and `null` on failure.
|
||||||
|
|
||||||
AnkiConnect can download audio, video, and picture files and embed them in newly created notes. The corresponding `audio`, `video`, and `picture` note members are
|
Anki-Connect can download audio, video, and picture files and embed them in newly created notes. The corresponding `audio`, `video`, and `picture` note members are
|
||||||
optional and can be omitted. If you choose to include any of them, they should contain a single object or an array of objects
|
optional and can be omitted. If you choose to include any of them, they should contain a single object or an array of objects
|
||||||
with the mandatory `filename` field and one of `data`, `path` or `url`. Refer to the documentation of `storeMediaFile` for an explanation of these fields.
|
with the mandatory `filename` field and one of `data`, `path` or `url`. Refer to the documentation of `storeMediaFile` for an explanation of these fields.
|
||||||
The `skipHash` field can be optionally provided to skip the inclusion of files with an MD5 hash that matches the provided value.
|
The `skipHash` field can be optionally provided to skip the inclusion of files with an MD5 hash that matches the provided value.
|
||||||
|
Loading…
Reference in New Issue
Block a user