Skip to content

Commit b73bed1

Browse files
LJSpillerLJSpiller
authored
Merge pull request #216022 from diberry/diberry/1026-cog-search-js
Cog Search - add search to website (update) - JS
2 parents 60ee1f2 + 45d9659 commit b73bed1

9 files changed

+282
-175
lines changed

‎articles/search/includes/tutorial-add-search-website-create-app.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
ms.topic: include
3+
ms.date: 10/26/2022
4+
author: HeidiSteen
5+
ms.author: heidist
6+
ms.service: cognitive-search
7+
---
8+
9+
Deploy the search-enabled website as an Azure Static Web Apps site. This deployment includes both the React app and the Function app.
10+
11+
The Static Web app pulls the information and files for deployment from GitHub using your fork of the samples repository.
12+
13+
## Create a Static Web App in Visual Studio Code
14+
15+
1. Select **Azure** from the Activity Bar, then open **Resources** from the Side bar.
16+
17+
1. Right-click **Static Web Apps** and then select **Create Static Web App (Advanced)**.
18+
19+
:::image type="content" source="../media/tutorial-javascript-create-load-index/visual-studio-code-create-static-web-app-resource-advanced.png" alt-text="Screenshot of Visual Studio Code, with the Azure Static Web Apps explorer showing the option to create an advanced static web app.":::
20+
21+
1. If you see a pop-up window in VS Code asking which branch you want to deploy from, select the default branch, usually **master** or **main**.
22+
23+
This setting means only changes you commit to that branch are deployed to your static web app.
24+
25+
1. If you see a pop-up window asking you to commit your changes, don't do this. The secrets from the bulk import step shouldn't be committed to the repository.
26+
27+
To roll back the changes, in VS Code select the Source Control icon in the Activity bar, then select each changed file in the Changes list and select the **Discard changes** icon.
28+
29+
1. Follow the prompts to provide the following information:
30+
31+
|Prompt|Enter|
32+
|--|--|
33+
|Select a resource group for new resources.|Use the resource group you created for this tutorial.|
34+
|Enter the name for the new Static Web App.|Create a unique name for your resource. For example, you can prepend your name to the repository name such as, `joansmith-azure-search-dotnet-samples`. |
35+
|Select a SKU| Select the free SKU for this tutorial.|
36+
|Select a location for new resources.|Select a region close to you.|
37+
|Choose build preset to configure default project structure.|Select **Custom**|
38+
|Select the location of your application code|`search-website-functions-v4/client`<br><br>This is the path, from the root of the repository, to your static web app. |
39+
|Enter the path of your build output...|`build`<br><br>This is the path, from your static web app, to your generated files.|
40+
41+
1. The resource is created and a notification window appears.
42+
43+
When the resource is created, it creates a GitHub action file on GitHub.
44+
45+
1. Select **Open Actions in GitHub** from the Notifications. This opens a browser window pointed to your forked repo.
46+
47+
Wait until the _workflow_ completes before continuing. This may take a minute or two to finish.
48+
49+
1. Pull the new GitHub action file to your local computer by synchronizing your local fork with your remote fork:
50+
51+
```bash
52+
git pull origin main
53+
```
54+
55+
* _origin_ refers to your forked repo.
56+
* _main_ refers to the default branch.
57+
58+
1. In Visual Studio file explorer, find and open the workflow file in the `./.github/workflows/` directory. The file path and name looks _something_ `.github\workflows\azure-static-web-apps-lemon-mushroom-0e1bd060f.yml`.
59+
60+
The _part_ of the YAML file relevant to the static web app is shown below:
61+
62+
:::code language="yml" source="~/azure-search-javascript-samples/search-website-functions-v4/example-github-action.yml" highlight="28-33":::
63+
64+
1. Edit your action file to contain the `api_location` property. If your local file doesn't have the property, add it below the `app_location` property.
65+
66+
```yml
67+
api_location: "search-website-functions-v4/api"
68+
```
69+
70+
1. Commit changes to your local repository.
71+
72+
```bash
73+
git add *.yml && git commit -m "update action for static web app"
74+
```
75+
76+
1. Push changes to GitHub.
77+
78+
```bash
79+
git push origin main
80+
```
81+
82+
The updated action in your remote fork creates a new build and deploy to your static web app. Wait until the _workflow_ completes before continuing. This may take a minute or two to finish.
83+
84+
## Get Cognitive Search query key in Visual Studio Code
85+
86+
1. In Visual Studio Code, open the [Activity bar](https://code.visualstudio.com/docs/getstarted/userinterface), and select the Azure icon.
87+
88+
1. In the Side bar, select your Azure subscription under the **Azure: Cognitive Search** area, then right-click on your Search resource and select **Copy Query Key**.
89+
90+
:::image type="content" source="../media/tutorial-javascript-create-load-index/visual-studio-code-copy-query-key.png" alt-text="Screenshot of Visual Studio Code showing the Azure Cognitive Search explorer, with the Copy Query Key option shown.":::
91+
92+
1. Keep this query key, you'll need to use it in the next section. The query key is able to query your Index.
93+
94+
## Add configuration settings in Azure portal
95+
96+
The Azure Function app won't return Search data until the Search secrets are in settings.
97+
98+
1. Select **Azure** from the Activity Bar.
99+
1. Right-click on your Static Web Apps resource then select **Open in Portal**.
100+
101+
:::image type="content" source="../media/tutorial-javascript-static-web-app/open-static-web-app-in-azure-portal.png" alt-text="Screenshot of Visual Studio Code showing Azure Static Web Apps explorer with the Open in Portal option shown.":::
102+
103+
1. Select **Configuration** then select **+ Add**.
104+
105+
:::image type="content" source="../media/tutorial-javascript-static-web-app/add-new-application-setting-to-static-web-app-in-portal.png" alt-text="Screenshot of Visual Studio Code showing the Azure Static Web Apps explorer with the Configuration option shown.":::
106+
107+
1. Add each of the following settings:
108+
109+
|Setting|Your Search resource value|
110+
|--|--|
111+
|SearchApiKey|Your Search query key|
112+
|SearchServiceName|Your Search resource name|
113+
|SearchIndexName|`good-books`|
114+
|SearchFacets|`authors*,language_code`|
115+
116+
Azure Cognitive Search requires different syntax for filtering collections than it does for strings. Add a `*` after a field name to denote that the field is of type `Collection(Edm.String)`. This allows the Azure Function to add filters correctly to queries.
117+
118+
1. Select **Save** to save the settings.
119+
120+
:::image type="content" source="../media/tutorial-javascript-static-web-app/save-new-application-setting-to-static-web-app-in-portal.png" alt-text="Screenshot of browser showing Azure portal with the button to save the settings for your app..":::
121+
122+
1. Return to VS Code.
123+
1. Refresh your static web app to see the application settings.
124+
125+
:::image type="content" source="../media/tutorial-javascript-static-web-app/visual-studio-code-extension-fresh-resource.png" alt-text="Screenshot of Visual Studio Code showing the Azure Static Web Apps explorer with the new application settings.":::
126+
127+
## Use search in your static web app
128+
129+
1. In Visual Studio Code, open the [Activity bar](https://code.visualstudio.com/docs/getstarted/userinterface), and select the Azure icon.
130+
1. In the Side bar, **right-click on your Azure subscription** under the `Static Web Apps` area and find the static web app you created for this tutorial.
131+
1. Right-click the static web app name and select **Browse site**.
132+
133+
:::image type="content" source="../media/tutorial-javascript-create-load-index/visual-studio-code-browse-static-web-app.png" alt-text="Screenshot of Visual Studio Code showing the Azure Static Web Apps explorer showing the **Browse site** option.":::
134+
135+
1. Select **Open** in the pop-up dialog.
136+
1. In the website search bar, enter a search query such as `code`, so the suggest feature suggests book titles. Select a suggestion or continue entering your own query. Press enter when you've completed your search query.
137+
1. Review the results then select one of the books to see more details.
138+
139+
140+
## Troubleshooting
141+
142+
[!INCLUDE [tutorial-troubleshooting](tutorial-add-search-website-troubleshooting.md)]
143+
144+
## Clean up resources
145+
146+
To clean up the resources created in this tutorial, delete the resource group.
147+
148+
1. In Visual Studio Code, open the [Activity bar](https://code.visualstudio.com/docs/getstarted/userinterface), and select the Azure icon.
149+
150+
1. In the Side bar, **right-click on your Azure subscription** under the `Resource Groups` area and find the resource group you created for this tutorial.
151+
1. Right-click the resource group name then select **Delete**.
152+
This deletes both the Search and Static Web Apps resources.
153+
1. If you no longer want the GitHub fork of the sample, remember to delete that on GitHub. Go to your fork's **Settings** then delete the fork.

‎articles/search/includes/tutorial-add-search-website-create-resource-group.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
ms.topic: include
3+
ms.date: 10/26/2022
4+
author: HeidiSteen
5+
ms.author: heidist
6+
ms.service: cognitive-search
7+
---
8+
9+
1. In Visual Studio Code, open the [Activity bar](https://code.visualstudio.com/docs/getstarted/userinterface), and select the Azure icon.
10+
1. In the **Resources** section, select Add (**+**), and then select **Create Resource Group**.
11+
12+
:::image type="content" source="../media/tutorial-javascript-overview/visual-studio-code-create-resource-group.png" alt-text="Screenshot of Visual Studio Code, in Azure explorer, showing **Create Resource Group** option.":::
13+
1. Enter a resource group name, such as `cognitive-search-website-tutorial`.
14+
1. Select a location close to you.
15+
1. When you create the Cognitive Search and Static Web Apps resources, later in the tutorial, use this resource group.
16+
17+
Creating a resource group gives you a logical unit to manage the resources, including deleting them when you're finished using them.

‎articles/search/includes/tutorial-add-search-website-fork-and-clone.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
ms.topic: include
3+
ms.date: 10/26/2022
4+
author: HeidiSteen
5+
ms.author: heidist
6+
ms.service: cognitive-search
7+
---
8+
9+
1. At a Bash terminal, download your forked sample application to your local computer.
10+
11+
Replace `YOUR-GITHUB-ALIAS` with your GitHub alias.
12+
13+
```bash
14+
git clone https://github.com/YOUR-GITHUB-ALIAS/azure-search-javascript-samples
15+
```
16+
17+
1. At the same Bash terminal, go into your forked repository for this website search example:
18+
19+
```bash
20+
cd azure-search-javascript-samples
21+
```
22+
23+
1. Use the Visual Studio Code command, `code .` to open your forked repository. The remaining tasks are accomplished from Visual Studio Code, unless specified.
24+
25+
```bash
26+
code .
27+
```

‎articles/search/includes/tutorial-add-search-website-troubleshooting.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
ms.topic: include
3+
ms.date: 10/26/2022
4+
author: HeidiSteen
5+
ms.author: heidist
6+
ms.service: cognitive-search
7+
---
8+
9+
If the web app didn't deploy or work, use the following list to determine and fix the issue:
10+
11+
* **Did the deployment succeed?**
12+
13+
In order to determine if your deployment succeeded, you need to go to _your_ fork of the sample repo and review the success or failure of the GitHub action. There should be only 1 action and it should have static web app settings for the `app_location`, `api_location`, and `output_location`. If the action didn't deploy successfully, dive into the action logs and look for the last failure.
14+
15+
* **Does the client (front-end) application work?**
16+
17+
You should be able to get to your web app and it should successfully display. If the deployment succeeded but the website doesn't display, this may be an issue with how the static web app is configured for rebuilding the app, once it is on Azure.
18+
19+
* **Does the API (serverless back-end) application work?**
20+
21+
You should be able to interact with the client app, searching for books and filtering. If the form doesn't return any values, open the browser's developer tools, and determine if the HTTP calls to the API were successful. If the calls weren't successful, the most likely reason if the static web app configurations for the API endpoint name and Search query key are incorrect.

‎articles/search/includes/tutorial-add-search-website-what-sample-does.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
ms.topic: include
3+
ms.date: 10/26/2022
4+
author: HeidiSteen
5+
ms.author: heidist
6+
ms.service: cognitive-search
7+
---
8+
This sample website provides access to a catalog of 10,000 books. A user can search the catalog by entering text in the search bar. While the user enters text, the website uses the search index's suggest feature to complete the text. Once the query finishes, the list of books is displayed with a portion of the details. A user can select a book to see all the details, stored in the search index, of the book.
9+
10+
:::image type="content" source="../media/tutorial-javascript-overview/cognitive-search-enabled-book-website.png" alt-text="This sample website provides access to a catalog of 10,000 books. A user can search the catalog by entering text in the search bar. While the user enters text, the website uses the search index's suggest feature to complete the text. Once the search finishes, the list of books is displayed with a portion of the details. A user can select a book to see all the details, stored in the search index, of the book.":::
11+
12+
The search experience includes:
13+
14+
* Search – provides search functionality for the application.
15+
* Suggest – provides suggestions as the user is typing in the search bar.
16+
* Document Lookup – looks up a document by ID to retrieve all of its contents for the details page.

‎articles/search/tutorial-javascript-create-load-index.md

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,17 @@ author: diberry
77
ms.author: diberry
88
ms.service: cognitive-search
99
ms.topic: tutorial
10-
ms.date: 05/21/2021
10+
ms.date: 10/26/2022
1111
ms.custom: devx-track-js
1212
ms.devlang: javascript
1313
---
1414

1515
# 2 - Create and load Search Index with JavaScript
1616

1717
Continue to build your Search-enabled website by:
18-
* Creating a Search resource with the VS Code extension
19-
* Creating a new index and importing data with JavaScript using the sample script and Azure SDK [@azure/search-documents](https://www.npmjs.com/package/@azure/search-documents).
18+
* Create a Search resource with the VS Code extension
19+
* Create a new index
20+
* Import data with JavaScript using the [sample script](https://github.com/Azure-Samples/azure-search-javascript-samples/blob/main/search-website-functions-v4/bulk-insert/bulk_insert_books.js) and Azure SDK [@azure/search-documents](https://www.npmjs.com/package/@azure/search-documents).
2021

2122
## Create an Azure Search resource
2223

@@ -47,7 +48,7 @@ Get your Search resource admin key with the Visual Studio Code extension.
4748

4849
:::image type="content" source="./media/tutorial-javascript-create-load-index/visual-studio-code-copy-admin-key.png" alt-text="In the Side bar, right-click on your Search resource and select **Copy Admin Key**.":::
4950

50-
1. Keep this admin key, you will need to use it in [a later section](#prepare-the-bulk-import-script-for-search).
51+
1. Keep this admin key, you'll need to use it in [a later section](#prepare-the-bulk-import-script-for-search).
5152

5253
## Prepare the bulk import script for Search
5354

@@ -56,22 +57,22 @@ The script uses the Azure SDK for Cognitive Search:
5657
* [npm package @azure/search-documents](https://www.npmjs.com/package/@azure/search-documents)
5758
* [Reference Documentation](/javascript/api/overview/azure/search-documents-readme)
5859

59-
1. In Visual Studio Code, open the `bulk_insert_books.js` file in the subdirectory, `search-website/bulk-insert`, replace the following variables with your own values to authenticate with the Azure Search SDK:
60+
1. In Visual Studio Code, open the `bulk_insert_books.js` file in the subdirectory, `search-website-functions-v4/bulk-insert`, replace the following variables with your own values to authenticate with the Azure Search SDK:
6061

6162
* YOUR-SEARCH-RESOURCE-NAME
6263
* YOUR-SEARCH-ADMIN-KEY
6364

64-
:::code language="javascript" source="~/azure-search-javascript-samples/search-website/bulk-insert/bulk_insert_books.js" highlight="16,17" :::
65+
:::code language="javascript" source="~/azure-search-javascript-samples/search-website-functions-v4/bulk-insert/bulk_insert_books.js" highlight="16,17" :::
6566

66-
1. Open an integrated terminal in Visual Studio for the project directory's subdirectory, `search-website/bulk-insert`, and run the following command to install the dependencies.
67+
1. Open an integrated terminal in Visual Studio for the project directory's subdirectory, `search-website-functions-v4/bulk-insert`, and run the following command to install the dependencies.
6768

6869
```bash
6970
npm install
7071
```
7172

7273
## Run the bulk import script for Search
7374

74-
1. Continue using the integrated terminal in Visual Studio for the project directory's subdirectory, `search-website/bulk-insert`, to run the following bash command to run the `bulk_insert_books.js` script:
75+
1. Continue using the integrated terminal in Visual Studio for the project directory's subdirectory, `search-website-functions-v4/bulk-insert`, to run the following bash command to run the `bulk_insert_books.js` script:
7576
7677
```javascript
7778
npm start
@@ -94,15 +95,15 @@ Once the upload completes, the Search Index is ready to use. Review your new Ind
9495
9596
## Rollback bulk import file changes
9697
97-
Use the following git command in the VS Code integrated terminal at the `bulk-insert` directory, to rollback the changes. They are not needed to continue the tutorial and you shouldn't save or push these secrets to your repo.
98+
Use the following git command in the VS Code integrated terminal at the `bulk-insert` directory, to roll back the changes. They aren't needed to continue the tutorial and you shouldn't save or push these secrets to your repo.
9899
99100
```git
100101
git checkout .
101102
```
102103
103104
## Copy your Search resource name
104105
105-
Note your **Search resource name**. You will need this to connect the Azure Function app to your Search resource.
106+
Note your **Search resource name**. You'll need this to connect the Azure Function app to your Search resource.
106107

107108
> [!CAUTION]
108109
> While you may be tempted to use your Search admin key in the Azure Function, that isn't following the principle of least privilege. The Azure Function will use the query key to conform to least privilege.

0 commit comments

Comments
 (0)