| 1 | # QnAMaker
|
| 2 |
|
| 3 | [](https://badge.fury.io/js/qnamaker)
|
| 4 |
|
| 5 | QnAMaker is command line tool and library for interacting with QnAMaker service using the QnAMaker REST API
|
| 6 |
|
| 7 | ## Pre-requisite
|
| 8 |
|
| 9 | - [Node.js](https://nodejs.org/) version 8.x or higher
|
| 10 |
|
| 11 | ## Installation
|
| 12 |
|
| 13 | ### As a cli
|
| 14 | Make sure you have node >=8.5 and npm installed on your machine. then use:
|
| 15 |
|
| 16 | `npm install -g qnamaker`
|
| 17 |
|
| 18 | ### As a library
|
| 19 | The QnAMaker apis can be installed and used as a library in any Node or UI JavaScript projects for the browser.
|
| 20 |
|
| 21 | `npm install -s qnamaker`
|
| 22 |
|
| 23 | You can then import and use service classes specific to the endpoint and operation you wish to call.
|
| 24 |
|
| 25 | ## Command line usage
|
| 26 |
|
| 27 | QnA Maker cli for interacting with the QnA Maker api - © 2018 Microsoft Corporation
|
| 28 |
|
| 29 | | Command | Description |
|
| 30 | |----------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
|
| 31 | | **Alterations** | |
|
| 32 | | `qnamaker list alterations` | Downloads all word alterations (synonyms) that have been automatically mined or added by the user. |
|
| 33 | | `qnamaker replace alterations --in wordAlterations.json` | Replaces word alterations (synonyms) for the KB with the give records. |
|
| 34 | | **Endpointkeys** | |
|
| 35 | | `qnamaker list endpointkeys` | list all the currently valid endpointKeys for querying your private endpoint |
|
| 36 | | `qnamaker refresh endpointkeys --keyType <string>` | Re-generates an endpoint key, in case you suspect your keys have been compromised |
|
| 37 | | **Kb** | |
|
| 38 | | `qnamaker create kb --in createKbPayload.json` | Create a new knowledgebase |
|
| 39 | | `qnamaker delete kb --kbId <string>` | Delete a knowledgebase by id |
|
| 40 | | `qnamaker export kb --kbId <string> --environment` | qnamaker export kb --kbId <string> --environment |
|
| 41 | | `<string>` | <string> |
|
| 42 | | `qnamaker get kb --kbId <string>` | Get metadata about a knowledgebase |
|
| 43 | | `qnamaker publish kb --kbId <string>` | Publish all unpublished in the knowledgebase to the prod endpoint |
|
| 44 | | `qnamaker replace kb --in replaceKb.json --kbId <string>`| Replace a knowledgebase contents with new contents |
|
| 45 | | `qnamaker update kb --in updateKb.json --kbId <string>` | Add or delete QnA Pairs and / or URLs to an existing knowledge base |
|
| 46 | | **Kbs** | |
|
| 47 | | `qnamaker list kbs` | List all of your knowledgebases |
|
| 48 | | **Legacykb** | |
|
| 49 | | `qnamaker export legacykb --kbId <legacyKB>` | Export legacy knowledgebase (requires legacy --kbid and --subscriptionKey to be passed in) |
|
| 50 | | **Operationdetails** | |
|
| 51 | | `qnamaker get operationdetails --operationId <string>` | Gets details of a specific long running operation. |
|
| 52 | | **Query** | |
|
| 53 | | `qnamaker query --question "how do I turn it on" --top 5`| Returns the list of answers for the given question sorted in descending order of ranking score. |
|
| 54 |
|
| 55 |
|
| 56 | ## Configuration
|
| 57 | A configuration object is required to provide the endpoint base path, app ID, version ID and the
|
| 58 | authoring key to each outbound call. There are 3 ways to provide this information to the cli
|
| 59 |
|
| 60 | 1. As a `.qnamakerrc` file in the cwd.
|
| 61 | The json format for the `.qnamakerrc` file is:
|
| 62 | ```json
|
| 63 | {
|
| 64 | "subscriptionKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
|
| 65 | "kbId": "xxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxx",
|
| 66 | "hostname": "https://xxxxxx.azurewebsites.net",
|
| 67 | "endpointKey": "xxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxx"
|
| 68 | }
|
| 69 | ```
|
| 70 |
|
| 71 | > NOTE: Simply run `qnamaker --init` to answer simple questions to create your .qnamakerrc file
|
| 72 |
|
| 73 | 2. As arguments to the cli. `--kbId <string> --subscriptionKey <string> `
|
| 74 |
|
| 75 | 3. As environment variables. `QNAMAKER_KBID, QNAMAKER_SUBSCRIPTION_KEY, QNAMAKER_ENDPOINTKEY, QNAMAKER_HOSTNAME`
|
| 76 |
|
| 77 | The cli will first look for these named configuration variables in the arguments list, then inside the `.qnamakerrc` file, then fallback to environment variables.
|
| 78 |
|
| 79 | ### Securing Your Access Key
|
| 80 | To better secure your access key, it's recommended to omit the key from the `.qnamakerrc`
|
| 81 | file and instead pass it in to the `--subscriptionKey` argument or store it as the `QNAMAKER_SUBSCRIPTION_KEY`
|
| 82 | environment variable. If security is not a concern for your particular case, all configuration items
|
| 83 | can be stored in the `.qnamaker` for convenience.
|
| 84 |
|
| 85 | ### Overriding Configurations
|
| 86 | Since configuration items can be passed as arguments to the cli, using arguments to specify
|
| 87 | the configuration will override the `.qnamakerrc` and any environment variables that may have been specified.
|
| 88 |
|