From d37a7945be053adacf47b1f736b1dfb4b7e7fd5e Mon Sep 17 00:00:00 2001 From: HeidiSteen Date: Tue, 27 Aug 2019 23:04:04 -0700 Subject: [PATCH] Postman collection for the cognitive search tutorial --- Quickstart/README.md | 2 +- README.md | 4 + Tutorial/CONTRIBUTING.md | 76 ++++ Tutorial/LICENSE.md | 21 ++ Tutorial/README.md | 50 +++ ...demo REST tutorial.postman_collection.json | 349 ++++++++++++++++++ 6 files changed, 501 insertions(+), 1 deletion(-) create mode 100644 Tutorial/CONTRIBUTING.md create mode 100644 Tutorial/LICENSE.md create mode 100644 Tutorial/README.md create mode 100644 Tutorial/cog-search-demo REST tutorial.postman_collection.json diff --git a/Quickstart/README.md b/Quickstart/README.md index 2c8220e..16a315e 100644 --- a/Quickstart/README.md +++ b/Quickstart/README.md @@ -2,7 +2,7 @@ page_type: sample languages: - rest -name: Quickstart in REST - Postman +name: Azure Search Quickstart in REST - Postman description: | Learn basic steps for creating, loading, and querying an Azure Search index using Postman Desktop app and the latest-version REST APIs. products: diff --git a/README.md b/README.md index d3ba65b..5e5a1bf 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,10 @@ To use these collections, import them into **Postman**. Includes 4 requests used to create an index, load documents, search the index, and query system information. Request bodies include JSON documents that provides index and documents. +## Tutorial collection + +This collection provides the same requests as those used to build the cognitive search pipeline in [REST Tutorial: Add structure to "unstructured content" with cognitive search](https://docs.microsoft.com/azure/search/cognitive-search-tutorial-blob). + ## Caselaw collection Includes 4 requests used to create an index, data source, skillset, and indexer using [Caselaw demo data](https://github.com/Azure-Samples/azure-search-sample-data/tree/master/caselaw) from Azure Search Sample Data. diff --git a/Tutorial/CONTRIBUTING.md b/Tutorial/CONTRIBUTING.md new file mode 100644 index 0000000..624db97 --- /dev/null +++ b/Tutorial/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# Contributing to the cognitive search tutorial + +This project welcomes contributions and suggestions. Most contributions require you to agree to a +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us +the rights to use your contribution. For details, visit https://cla.microsoft.com. + +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide +a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions +provided by the bot. You will only need to do this once across all repos using our CLA. + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + + - [Code of Conduct](#coc) + - [Issues and Bugs](#issue) + - [Feature Requests](#feature) + - [Submission Guidelines](#submit) + +## Code of Conduct +Help us keep this project open and inclusive. Please read and follow our [Code of Conduct](https://opensource.microsoft.com/codeofconduct/). + +## Found an Issue? +If you find a bug in the source code or a mistake in the documentation, you can help us by +[submitting an issue](#submit-issue) to the GitHub Repository. Even better, you can +[submit a Pull Request](#submit-pr) with a fix. + +## Want a Feature? +You can *request* a new feature by [submitting an issue](#submit-issue) to the GitHub +Repository. If you would like to *implement* a new feature, please submit an issue with +a proposal for your work first, to be sure that we can use it. + +* **Small Features** can be crafted and directly [submitted as a Pull Request](#submit-pr). + +## Submission Guidelines + +### Submitting an Issue +Before you submit an issue, search the archive, maybe your question was already answered. + +If your issue appears to be a bug, and hasn't been reported, open a new issue. +Help us to maximize the effort we can spend fixing issues and adding new +features, by not reporting duplicate issues. Providing the following information will increase the +chances of your issue being dealt with quickly: + +* **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps +* **Version** - what version is affected (e.g. 0.1.2) +* **Motivation for or Use Case** - explain what are you trying to do and why the current behavior is a bug for you +* **Browsers and Operating System** - is this a problem with all browsers? +* **Reproduce the Error** - provide a live example or a unambiguous set of steps +* **Related Issues** - has a similar issue been reported before? +* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be + causing the problem (line of code or commit) + +You can file new issues by providing the above information at the corresponding repository's issues link: https://github.com/[organization-name]/[repository-name]/issues/new]. + +### Submitting a Pull Request (PR) +Before you submit your Pull Request (PR) consider the following guidelines: + +* Search the repository (https://github.com/[organization-name]/[repository-name]/pulls) for an open or closed PR + that relates to your submission. You don't want to duplicate effort. + +* Make your changes in a new git fork: + +* Commit your changes using a descriptive commit message +* Push your fork to GitHub: +* In GitHub, create a pull request +* If we suggest changes then: + * Make the required updates. + * Rebase your fork and force push to your GitHub repository (this will update your Pull Request): + + ```shell + git rebase master -i + git push -f + ``` + +That's it! Thank you for your contribution! diff --git a/Tutorial/LICENSE.md b/Tutorial/LICENSE.md new file mode 100644 index 0000000..d1ca00f --- /dev/null +++ b/Tutorial/LICENSE.md @@ -0,0 +1,21 @@ + MIT License + + Copyright (c) Microsoft Corporation. All rights reserved. + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE \ No newline at end of file diff --git a/Tutorial/README.md b/Tutorial/README.md new file mode 100644 index 0000000..41231f7 --- /dev/null +++ b/Tutorial/README.md @@ -0,0 +1,50 @@ +--- +page_type: sample +languages: + - rest +name: Cognitive Search Tutorial in REST - Postman +description: | + Learn how to create a cognitive search pipeline to extract information and structure from unstructured blobs.. +products: + - azure + - azure-search +urlFragment: rest-api-tutorial +--- + +# Cognitive search sample for Azure Search using REST APIs and Postman + +![Flask sample MIT license badge](https://img.shields.io/badge/license-MIT-green.svg) + +Demonstrates using Postman and the Azure Search REST APIs to send requests to Azure Search: create a data source, a skillset, index, and indexer. Requests are provided in the V2 collection format, which you can import and then modify for connections to your Azure Search service. + +This collection is featured in the [REST Tutorial: Add structure to "unstructured content" with cognitive search](https://docs.microsoft.com/azure/search/cognitive-search-tutorial-blob). When you import the collection, modify the headers and URL to use your service name and API key. The purpose of this sample is to demonstrate how creating a cognitive search pipeline adds new information and structure to unstructured files. + +## Contents + +| File/folder | Description | +|-------------|-------------| +| `cog-search-demo REST tutorial.postman_collection.json` | Import into Postman | +| `.gitignore` | Define what to ignore at commit time. | +| `CONTRIBUTING.md` | Guidelines for contributing to the sample. | +| `README.md` | This README file. | +| `LICENSE` | The license for the sample. | + +## Prerequisites + +- [Postman Desktop app](https://www.getpostman.com/) +- [Azure Search service](https://docs.microsoft.com/azure/search/search-create-service-portal) + +## Setup + +1. Clone or download this sample repository. +1. Extract contents if the download is a zip file. Make sure the files are read-write. + +### Running quickstart +1. Start Postman and import cog-search-demo REST tutorial.postman_collection.json +1. For each request, update the Header to use the admin api-key of your service, which you can obtain from the portal. +1. Next, update the URL of each request to use the name of your search service. +1. Send each request to the service. + +## Next steps + +You can learn more about Azure Search on the [official documentation site](https://docs.microsoft.com/azure/search). \ No newline at end of file diff --git a/Tutorial/cog-search-demo REST tutorial.postman_collection.json b/Tutorial/cog-search-demo REST tutorial.postman_collection.json new file mode 100644 index 0000000..2b9af2c --- /dev/null +++ b/Tutorial/cog-search-demo REST tutorial.postman_collection.json @@ -0,0 +1,349 @@ +{ + "info": { + "_postman_id": "bcd06aea-a9ff-4884-aa60-552be6a7d37c", + "name": "cog-search-demo REST tutorial", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" + }, + "item": [ + { + "name": "1 - Create data source", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json", + "type": "text" + }, + { + "key": "api-key", + "value": "", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "{\r\n \"name\" : \"cog-search-demo-ds2\",\r\n \"description\" : \"Demo files to demonstrate cognitive search capabilities.\",\r\n \"type\" : \"azureblob\",\r\n \"credentials\" :\r\n { \"connectionString\" :\r\n \"DefaultEndpointsProtocol=https;AccountName=heidicogsearchdemo;AccountKey=J56zNOCiiI4r9m1WWH4VMX5mu8hJ79dWB3RZBn5tmXDKVlRSUNRO2onisXuxcySt0IRVwckvnD/+MieF0rcUGg==;EndpointSuffix=core.windows.net;\"\r\n },\r\n \"container\" : { \"name\" : \"cog-search-demo\" }\r\n}" + }, + "url": { + "raw": "https://Y.search.windows.net/datasources?api-version=2019-05-06", + "protocol": "https", + "host": [ + "Y", + "search", + "windows", + "net" + ], + "path": [ + "datasources" + ], + "query": [ + { + "key": "api-version", + "value": "2019-05-06" + } + ] + } + }, + "response": [] + }, + { + "name": "2 - Create Skills", + "request": { + "method": "PUT", + "header": [ + { + "key": "Content-Type", + "type": "text", + "value": "application/json" + }, + { + "key": "api-key", + "type": "text", + "value": "" + } + ], + "body": { + "mode": "raw", + "raw": "{\r\n \"description\": \"Extract entities, detect language and extract key-phrases\",\r\n \"skills\":\r\n [\r\n {\r\n \"@odata.type\": \"#Microsoft.Skills.Text.EntityRecognitionSkill\",\r\n \"categories\": [ \"Person\", \"Organization\", \"Location\" ],\r\n \"defaultLanguageCode\": \"en\",\r\n \"inputs\": [\r\n { \"name\": \"text\", \"source\": \"/document/content\" }\r\n ],\r\n \"outputs\": [\r\n { \"name\": \"persons\", \"targetName\": \"persons\" },\r\n { \"name\": \"organizations\", \"targetName\": \"organizations\" },\r\n { \"name\": \"locations\", \"targetName\": \"locations\" }\r\n ]\r\n },\r\n {\r\n \"@odata.type\": \"#Microsoft.Skills.Text.LanguageDetectionSkill\",\r\n \"inputs\": [\r\n { \"name\": \"text\", \"source\": \"/document/content\" }\r\n ],\r\n \"outputs\": [\r\n { \"name\": \"languageCode\", \"targetName\": \"languageCode\" }\r\n ]\r\n },\r\n {\r\n \"@odata.type\": \"#Microsoft.Skills.Text.SplitSkill\",\r\n \"textSplitMode\" : \"pages\",\r\n \"maximumPageLength\": 4000,\r\n \"inputs\": [\r\n { \"name\": \"text\", \"source\": \"/document/content\" },\r\n { \"name\": \"languageCode\", \"source\": \"/document/languageCode\" }\r\n ],\r\n \"outputs\": [\r\n { \"name\": \"textItems\", \"targetName\": \"pages\" }\r\n ]\r\n },\r\n {\r\n \"@odata.type\": \"#Microsoft.Skills.Text.KeyPhraseExtractionSkill\",\r\n \"context\": \"/document/pages/*\",\r\n \"inputs\": [\r\n { \"name\": \"text\", \"source\": \"/document/pages/*\" },\r\n { \"name\":\"languageCode\", \"source\": \"/document/languageCode\" }\r\n ],\r\n \"outputs\": [\r\n { \"name\": \"keyPhrases\", \"targetName\": \"keyPhrases\" }\r\n ]\r\n }\r\n ]\r\n}" + }, + "url": { + "raw": "https://.search.windows.net/skillsets/cog-search-demo-ss?api-version=2019-05-06", + "protocol": "https", + "host": [ + "", + "search", + "windows", + "net" + ], + "path": [ + "skillsets", + "cog-search-demo-ss" + ], + "query": [ + { + "key": "api-version", + "value": "2019-05-06" + } + ] + } + }, + "response": [] + }, + { + "name": "3 - Create index", + "request": { + "method": "PUT", + "header": [ + { + "key": "Content-Type", + "type": "text", + "value": "application/json" + }, + { + "key": "api-key", + "type": "text", + "value": "" + } + ], + "body": { + "mode": "raw", + "raw": "{\r\n \"fields\": [\r\n {\r\n \"name\": \"id\",\r\n \"type\": \"Edm.String\",\r\n \"key\": true,\r\n \"searchable\": true,\r\n \"filterable\": false,\r\n \"facetable\": false,\r\n \"sortable\": true\r\n },\r\n {\r\n \"name\": \"metadata_storage_name\",\r\n \"type\": \"Edm.String\",\r\n \"searchable\": false,\r\n \"filterable\": false,\r\n \"facetable\": false,\r\n \"sortable\": false\r\n },\r\n {\r\n \"name\": \"content\",\r\n \"type\": \"Edm.String\",\r\n \"sortable\": false,\r\n \"searchable\": true,\r\n \"filterable\": false,\r\n \"facetable\": false\r\n },\r\n {\r\n \"name\": \"languageCode\",\r\n \"type\": \"Edm.String\",\r\n \"searchable\": true,\r\n \"filterable\": false,\r\n \"facetable\": false\r\n },\r\n {\r\n \"name\": \"keyPhrases\",\r\n \"type\": \"Collection(Edm.String)\",\r\n \"searchable\": true,\r\n \"filterable\": false,\r\n \"facetable\": false\r\n },\r\n {\r\n \"name\": \"persons\",\r\n \"type\": \"Collection(Edm.String)\",\r\n \"searchable\": true,\r\n \"sortable\": false,\r\n \"filterable\": true,\r\n \"facetable\": true\r\n },\r\n {\r\n \"name\": \"organizations\",\r\n \"type\": \"Collection(Edm.String)\",\r\n \"searchable\": true,\r\n \"sortable\": false,\r\n \"filterable\": true,\r\n \"facetable\": true\r\n },\r\n {\r\n \"name\": \"locations\",\r\n \"type\": \"Collection(Edm.String)\",\r\n \"searchable\": true,\r\n \"sortable\": false,\r\n \"filterable\": true,\r\n \"facetable\": true\r\n }\r\n ]\r\n}" + }, + "url": { + "raw": "https://.search.windows.net/indexes/cog-search-demo-idx?api-version=2019-05-06", + "protocol": "https", + "host": [ + "", + "search", + "windows", + "net" + ], + "path": [ + "indexes", + "cog-search-demo-idx" + ], + "query": [ + { + "key": "api-version", + "value": "2019-05-06" + } + ] + } + }, + "response": [] + }, + { + "name": "4 - Create indexer", + "request": { + "method": "PUT", + "header": [ + { + "key": "Content-Type", + "type": "text", + "value": "application/json" + }, + { + "key": "api-key", + "type": "text", + "value": "" + } + ], + "body": { + "mode": "raw", + "raw": "{\r\n \"name\":\"cog-search-demo-idxr\",\t\r\n \"dataSourceName\" : \"cog-search-demo-ds\",\r\n \"targetIndexName\" : \"cog-search-demo-idx\",\r\n \"skillsetName\" : \"cog-search-demo-ss\",\r\n \"fieldMappings\" : [\r\n {\r\n \"sourceFieldName\" : \"metadata_storage_path\",\r\n \"targetFieldName\" : \"id\",\r\n \"mappingFunction\" :\r\n { \"name\" : \"base64Encode\" }\r\n },\r\n {\r\n \"sourceFieldName\" : \"metadata_storage_name\",\r\n \"targetFieldName\" : \"metadata_storage_name\",\r\n \"mappingFunction\" :\r\n { \"name\" : \"base64Encode\" }\r\n },\r\n {\r\n \"sourceFieldName\" : \"content\",\r\n \"targetFieldName\" : \"content\"\r\n }\r\n ],\r\n \"outputFieldMappings\" :\r\n [\r\n {\r\n \"sourceFieldName\" : \"/document/persons\",\r\n \"targetFieldName\" : \"persons\"\r\n },\r\n {\r\n \"sourceFieldName\" : \"/document/organizations\",\r\n \"targetFieldName\" : \"organizations\"\r\n },\r\n {\r\n \"sourceFieldName\" : \"/document/locations\",\r\n \"targetFieldName\" : \"locations\"\r\n },\r\n {\r\n \"sourceFieldName\" : \"/document/pages/*/keyPhrases/*\",\r\n \"targetFieldName\" : \"keyPhrases\"\r\n },\r\n {\r\n \"sourceFieldName\": \"/document/languageCode\",\r\n \"targetFieldName\": \"languageCode\"\r\n }\r\n ],\r\n \"parameters\":\r\n {\r\n \"maxFailedItems\":-1,\r\n \"maxFailedItemsPerBatch\":-1,\r\n \"configuration\":\r\n {\r\n \"dataToExtract\": \"contentAndMetadata\",\r\n \"parsingMode\": \"default\",\r\n \"firstLineContainsHeaders\": false,\r\n \"delimitedTextDelimiter\": \",\"\r\n }\r\n }\r\n}" + }, + "url": { + "raw": "https://.search.windows.net/indexers/cog-search-demo-idxr?api-version=2019-05-06", + "protocol": "https", + "host": [ + "", + "search", + "windows", + "net" + ], + "path": [ + "indexers", + "cog-search-demo-idxr" + ], + "query": [ + { + "key": "api-version", + "value": "2019-05-06" + } + ] + } + }, + "response": [] + }, + { + "name": "5 - Get Indexer Status", + "protocolProfileBehavior": { + "disableBodyPruning": true + }, + "request": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "type": "text", + "value": "application/json" + }, + { + "key": "api-key", + "type": "text", + "value": "" + } + ], + "body": { + "mode": "raw", + "raw": "" + }, + "url": { + "raw": "https://.search.windows.net/indexers/cog-search-demo-idxr/status?api-version=2019-05-06", + "protocol": "https", + "host": [ + "", + "search", + "windows", + "net" + ], + "path": [ + "indexers", + "cog-search-demo-idxr", + "status" + ], + "query": [ + { + "key": "api-version", + "value": "2019-05-06" + } + ] + } + }, + "response": [] + }, + { + "name": "6 - Query content field", + "protocolProfileBehavior": { + "disableBodyPruning": true + }, + "request": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "type": "text", + "value": "application/json" + }, + { + "key": "api-key", + "type": "text", + "value": "" + } + ], + "body": { + "mode": "raw", + "raw": "" + }, + "url": { + "raw": "https://.search.windows.net/indexes/cog-search-demo-idx/docs?search=*&$select=content&$count=true&api-version=2019-05-06", + "protocol": "https", + "host": [ + "", + "search", + "windows", + "net" + ], + "path": [ + "indexes", + "cog-search-demo-idx", + "docs" + ], + "query": [ + { + "key": "search", + "value": "*" + }, + { + "key": "$select", + "value": "content" + }, + { + "key": "$count", + "value": "true" + }, + { + "key": "api-version", + "value": "2019-05-06" + } + ] + } + }, + "response": [] + }, + { + "name": "6 - Add a filter", + "protocolProfileBehavior": { + "disableBodyPruning": true + }, + "request": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "type": "text", + "value": "application/json" + }, + { + "key": "api-key", + "type": "text", + "value": "" + } + ], + "body": { + "mode": "raw", + "raw": "" + }, + "url": { + "raw": "https://.search.windows.net/indexes/cog-search-demo-idx/docs?search=*&$filter=organizations/any(organizations: organizations eq 'NASDAQ')&$select=metadata_storage_name,organizations&$count=true&api-version=2019-05-06", + "protocol": "https", + "host": [ + "", + "search", + "windows", + "net" + ], + "path": [ + "indexes", + "cog-search-demo-idx", + "docs" + ], + "query": [ + { + "key": "search", + "value": "*" + }, + { + "key": "$filter", + "value": "organizations/any(organizations: organizations eq 'NASDAQ')" + }, + { + "key": "$select", + "value": "metadata_storage_name,organizations" + }, + { + "key": "$count", + "value": "true" + }, + { + "key": "api-version", + "value": "2019-05-06" + } + ] + } + }, + "response": [] + } + ] +} \ No newline at end of file