Skip to content

Commit be5eb44

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #248050 from ericasp16/add-core-languages-acs-number-lookup-quickstart
Add core languages acs number lookup quickstart
2 parents 1fa7eb0 + 6271c6a commit be5eb44

File tree

6 files changed

+594
-130
lines changed

6 files changed

+594
-130
lines changed

‎articles/communication-services/quickstarts/telephony/includes/number-lookup-java.md

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
Get started with the Phone Numbers client library for Java to look up operator information for phone numbers, which can be used to determine whether and how to communicate with that phone number. Follow these steps to install the package and look up operator information about a phone number.
2+
3+
> [!NOTE]
4+
> Find the code for this quickstart on [GitHub](https://github.com/Azure/communication-preview/tree/master/samples/NumberLookup).
5+
6+
## Prerequisites
7+
8+
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
9+
- [Java Development Kit (JDK)](/java/azure/jdk/?preserve-view=true&view=azure-java-stable) version 8 or above.
10+
- [Apache Maven](https://maven.apache.org/download.cgi).
11+
- An active Communication Services resource and connection string. [Create a Communication Services resource](../../create-communication-resource.md).
12+
13+
### Prerequisite check
14+
15+
In a terminal or command window, run the `mvn -v` command to check that Maven is installed.
16+
17+
## Setting up
18+
19+
To set up an environment for sending lookup queries, take the steps in the following sections.
20+
21+
### Create a new Java application
22+
23+
In a terminal or command window, navigate to the directory where you'd like to create your Java application. Run the following command to generate the Java project from the maven-archetype-quickstart template.
24+
25+
```console
26+
mvn archetype:generate -DgroupId=com.communication.lookup.quickstart -DartifactId=communication-lookup-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
27+
```
28+
29+
The 'generate' task creates a directory with the same name as the `artifactId`. Under this directory, the src/main/java directory contains the project source code, the `src/test/java directory` contains the test source, and the `pom.xml` file is the project's Project Object Model, or POM.
30+
31+
### Connect to dev package feed
32+
The public preview version of the SDK is published to a dev package feed. To connect to the dev feed, open the **pom.xml** file in your text editor and add the dev repo to **both** your pom.xml's `<repositories>` and `<distributionManagement>` sections
33+
34+
```xml
35+
<repository>
36+
<id>azure-sdk-for-java</id>
37+
<url>https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-java/maven/v1</url>
38+
<releases>
39+
<enabled>true</enabled>
40+
</releases>
41+
<snapshots>
42+
<enabled>true</enabled>
43+
</snapshots>
44+
</repository>
45+
```
46+
47+
Add or edit the `settings.xml` file in `${user.home}/.m2`
48+
49+
```xml
50+
<server>
51+
<id>azure-sdk-for-java</id>
52+
<username>azure-sdk</username>
53+
<password>[PERSONAL_ACCESS_TOKEN]</password>
54+
</server>
55+
```
56+
57+
Finally, generate a [Personal Access Token](https://dev.azure.com/azure-sdk/_details/security/tokens) with _Packaging_ read & write scopes and paste it into the `<password>` tag.
58+
59+
More detailed information and other options for connecting to the dev feed can be found [here](https://dev.azure.com/azure-sdk/public/_artifacts/feed/azure-sdk-for-java/connect).
60+
61+
### Install the package
62+
Add the following dependency elements to the group of dependencies in the **pom.xml** file.
63+
64+
```xml
65+
<dependencies>
66+
<dependency>
67+
<groupId>com.azure</groupId>
68+
<artifactId>azure-communication-common</artifactId>
69+
<version>1.0.0</version>
70+
</dependency>
71+
72+
<dependency>
73+
<groupId>com.azure</groupId>
74+
<artifactId>azure-communication-phonenumbers</artifactId>
75+
<version>1.2.0-beta.1</version>
76+
</dependency>
77+
78+
<dependency>
79+
<groupId>com.azure</groupId>
80+
<artifactId>azure-identity</artifactId>
81+
<version>1.2.3</version>
82+
</dependency>
83+
84+
<dependency>
85+
<groupId>com.azure</groupId>
86+
<artifactId>azure-core</artifactId>
87+
<version>1.41.0</version>
88+
</dependency>
89+
</dependencies>
90+
```
91+
92+
## Code examples
93+
94+
### Set up the app framework
95+
96+
From the project directory:
97+
98+
1. Navigate to the */src/main/java/com/communication/lookup/quickstart* directory
99+
1. Open the *App.java* file in your editor
100+
1. Replace the `System.out.println("Hello world!");` statement
101+
1. Add `import` directives
102+
103+
Use the following code to begin:
104+
105+
```java
106+
package com.communication.lookup.quickstart;
107+
108+
import com.azure.communication.phonenumbers.*;
109+
import com.azure.communication.phonenumbers.models.*;
110+
import com.azure.core.http.rest.*;
111+
import com.azure.core.util.Context;
112+
import com.azure.identity.*;
113+
import java.io.*;
114+
import java.util.ArrayList;
115+
116+
public class App
117+
{
118+
public static void main( String[] args ) throws IOException
119+
{
120+
System.out.println("Azure Communication Services - Number Lookup Quickstart");
121+
// Quickstart code goes here
122+
}
123+
}
124+
```
125+
126+
### Authenticate the client
127+
128+
## Authenticate the Phone Numbers Client
129+
130+
The `PhoneNumberClientBuilder` is enabled to use Azure Active Directory Authentication. Using the `DefaultAzureCredentialBuilder` is the easiest way to get started with Azure Active Directory. You can acquire your resource name from an Azure Communication Services resource in the [Azure portal](https://portal.azure.com).
131+
<!-- embedme ./src/samples/java/com/azure/communication/phonenumbers/ReadmeSamples.java#L52-L62 -->
132+
```java
133+
// You can find your resource name from your resource in the Azure portal
134+
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
135+
136+
PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
137+
.endpoint(endpoint)
138+
.credential(new DefaultAzureCredentialBuilder().build())
139+
.buildClient();
140+
```
141+
142+
Alternatively, the client can be authenticated using a connection string, also acquired from an Azure Communication Services resource in the [Azure portal](https://portal.azure.com). It's recommended to use a `COMMUNICATION_SERVICES_CONNECTION_STRING` environment variable to avoid putting your connection string in plain text within your code. Learn how to [manage your resource's connection string](../../create-communication-resource.md#store-your-connection-string).
143+
<!-- embedme ./src/samples/java/com/azure/communication/phonenumbers/ReadmeSamples.java#L30-L41 -->
144+
```java
145+
// This code retrieves your connection string from an environment variable
146+
String connectionString = System.getenv("COMMUNICATION_SERVICES_CONNECTION_STRING");
147+
148+
PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
149+
.connectionString(connectionString)
150+
.buildClient();
151+
```
152+
153+
### Look up operator information for a number
154+
155+
To search for a phone number's operator information, call `searchOperatorInformation` from the `PhoneNumbersClient`.
156+
157+
```java
158+
ArrayList<String> phoneNumbers = new ArrayList<String>();
159+
phoneNumbers.add("<target-phone-number>");
160+
OperatorInformationResult result = phoneNumberClient.searchOperatorInformation(phoneNumbers);
161+
```
162+
163+
Replace `<target-phone-number>` with the phone number you're looking up, usually a number you'd like to send a message to.
164+
165+
> [!WARNING]
166+
> Provide phone numbers in E.164 international standard format, for example, +14255550123.
167+
168+
### Use operator information
169+
170+
You can now use the operator information. For this quickstart guide, we can print some of the details to the console.
171+
172+
```java
173+
OperatorInformation operatorInfo = result.getValues().get(0);
174+
175+
String numberType = operatorInfo.getNumberType() == null ? "unknown" : operatorInfo.getNumberType().toString();
176+
String operatorName = "an unknown operator";
177+
if (operatorInfo.getOperatorDetails()!= null && operatorInfo.getOperatorDetails().getName() != null)
178+
{
179+
operatorName = operatorInfo.getOperatorDetails().getName();
180+
}
181+
System.out.println(operatorInfo.getPhoneNumber() + " is a " + numberType + " number, operated by " + operatorName);
182+
```
183+
184+
You may also use the operator information to determine whether to send an SMS. For more information on sending an SMS, see the [SMS Quickstart](../../sms/send.md).
185+
186+
## Run the code
187+
188+
Run the application from your terminal or command window with the following commands:
189+
Navigate to the directory containing the *pom.xml* file and compile the project.
190+
191+
```console
192+
mvn compile
193+
```
194+
195+
Then, build the package.
196+
197+
```console
198+
mvn package
199+
```
200+
201+
Run the following `mvn` command to execute the app.
202+
203+
```console
204+
mvn exec:java -Dexec.mainClass="com.communication.lookup.quickstart.App" -Dexec.cleanupDaemonThreads=false
205+
```
206+
207+
## Sample code
208+
209+
You can download the sample app from [GitHub](https://github.com/Azure/communication-preview/tree/master/samples/NumberLookup).

‎articles/communication-services/quickstarts/telephony/includes/number-lookup-js.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
Get started with the Phone Numbers client library for JavaScript to look up operator information for phone numbers, which can be used to determine whether and how to communicate with that phone number. Follow these steps to install the package and look up operator information about a phone number.
2+
3+
> [!NOTE]
4+
> Find the code for this quickstart on [GitHub](https://github.com/Azure/communication-preview/tree/master/samples/NumberLookup).
5+
6+
## Prerequisites
7+
8+
- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
9+
- [Node.js](https://nodejs.org/) Active LTS and Maintenance LTS versions (8.11.1 and 10.14.1 recommended).
10+
- An active Communication Services resource and connection string. [Create a Communication Services resource](../../create-communication-resource.md).
11+
12+
### Prerequisite check
13+
14+
In a terminal or command window, run the `node --version` command to check that Node.js is installed.
15+
16+
## Setting up
17+
18+
To set up an environment for sending lookup queries, take the steps in the following sections.
19+
20+
### Create a new Node.js Application
21+
22+
In a terminal or command window, create a new directory for your app and navigate to it.
23+
24+
```console
25+
mkdir number-lookup-quickstart && cd number-lookup-quickstart
26+
```
27+
28+
Run `npm init -y` to create a **package.json** file with default settings.
29+
30+
```console
31+
npm init -y
32+
```
33+
34+
Create a file called **number-lookup-quickstart.js** in the root of the directory you created. Add the following snippet to it:
35+
36+
```javascript
37+
async function main() {
38+
// quickstart code will here
39+
}
40+
41+
main();
42+
```
43+
44+
### Install the package
45+
46+
Use the `npm install` command to install the Azure Communication Services Phone Numbers client library for JavaScript.
47+
48+
```console
49+
npm install @azure/[email protected] --save
50+
```
51+
52+
The `--save` option adds the library as a dependency in your **package.json** file.
53+
54+
## Code examples
55+
56+
### Authenticate the client
57+
58+
Import the **PhoneNumbersClient** from the client library and instantiate it with your connection string, which can be acquired from an Azure Communication Services resource in the [Azure portal](https://portal.azure.com). It's recommended to use a `COMMUNICATION_SERVICES_CONNECTION_STRING` environment variable to avoid putting your connection string in plain text within your code. Learn how to [manage your resource's connection string](../../create-communication-resource.md#store-your-connection-string).
59+
60+
Add the following code to the top of **phone-numbers-quickstart.js**:
61+
62+
```javascript
63+
const { PhoneNumbersClient } = require('@azure/communication-phone-numbers');
64+
65+
// This code retrieves your connection string from an environment variable
66+
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];
67+
68+
// Instantiate the phone numbers client
69+
const phoneNumbersClient = new PhoneNumbersClient(connectionString);
70+
```
71+
72+
### Look up operator information for a number
73+
74+
To search for a phone number's operator information, call `searchOperatorInformation` from the `PhoneNumbersClient`.
75+
76+
```javascript
77+
let results = await phoneNumbersClient.searchOperatorInformation([ "<target-phone-number>" ]);
78+
```
79+
80+
Replace `<target-phone-number>` with the phone number you're looking up, usually a number you'd like to send a message to.
81+
82+
> [!WARNING]
83+
> Provide phone numbers in E.164 international standard format, for example, +14255550123.
84+
85+
### Use operator information
86+
87+
You can now use the operator information. For this quickstart guide, we can print some of the details to the console.
88+
89+
```javascript
90+
let operatorInfo = results.values[0];
91+
console.log(operatorInfo.phoneNumber + " is a " + (operatorInfo.numberType ? operatorInfo.numberType : "unknown") + " number, operated by " + (operatorInfo.operatorDetails.name ? operatorInfo.operatorDetails.name : "an unknown operator"));
92+
```
93+
94+
You may also use the operator information to determine whether to send an SMS. For more information on sending an SMS, see the [SMS Quickstart](../../sms/send.md).
95+
96+
## Run the code
97+
98+
Run the application from your terminal or command window with the `node` command.
99+
100+
```console
101+
node number-lookup-quickstart.js
102+
```
103+
104+
## Sample code
105+
106+
You can download the sample app from [GitHub](https://github.com/Azure/communication-preview/tree/master/samples/NumberLookup).

0 commit comments

Comments
 (0)