|
| 1 | +## Azure Communications Rooms Service client library for Java |
| 2 | + |
| 3 | +Azure Communication Rooms is used to operate on rooms. |
| 4 | + |
| 5 | +[Source code][source] | [Package (Maven)][package] | [API reference documentation][api_documentation] |
| 6 | +| [Product documentation][product_docs] |
| 7 | + |
| 8 | +## Getting started |
| 9 | + |
| 10 | +### Prerequisites |
| 11 | + |
| 12 | +- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). |
| 13 | +- [Java Development Kit (JDK)](https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable) version 8 or above. |
| 14 | +- [Apache Maven](https://maven.apache.org/download.cgi). |
| 15 | +- A deployed Communication Services resource. You can use the [Azure Portal](https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) or the [Azure PowerShell](https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice) to set it up. |
| 16 | + |
| 17 | +### Include the package |
| 18 | + |
| 19 | +#### Include direct dependency |
| 20 | +If you want to take dependency on a particular version of the library that is not present in the BOM, |
| 21 | +add the direct dependency to your project as follows. |
| 22 | + |
| 23 | +[//]: # ({x-version-update-start;com.azure:azure-communication-rooms;current}) |
| 24 | +```xml |
| 25 | +<dependency> |
| 26 | + <groupId>com.azure</groupId> |
| 27 | + <artifactId>azure-communication-rooms</artifactId> |
| 28 | + <version>1.0.0-beta.1</version> |
| 29 | +</dependency> |
| 30 | +``` |
| 31 | + |
| 32 | +## Authenticate the client |
| 33 | + |
| 34 | +### Azure Active Directory Token Authentication |
| 35 | +A `DefaultAzureCredential` object must be passed to the `RoomsClientBuilder` via the credential() function. Endpoint and httpClient must also be set via the endpoint() and httpClient() functions respectively. |
| 36 | + |
| 37 | +`AZURE_CLIENT_SECRET`, `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` environment variables |
| 38 | +are needed to create a DefaultAzureCredential object. |
| 39 | + |
| 40 | +Alternatively, you can provide the entire connection string using the connectionString() function instead of providing the endpoint and access key. |
| 41 | + |
| 42 | +```java readme-sample-createRoomsClientWithConnectionString |
| 43 | + |
| 44 | +public RoomsClient createRoomsClientWithConnectionString() { |
| 45 | + // You can find your connection string from your resource in the Azure Portal |
| 46 | + String connectionString = "https://<resource-name>.communication.azure.com/;<access-key>"; |
| 47 | + |
| 48 | + RoomsClient roomsClient = new RoomsClientBuilder().connectionString(connectionString).buildClient(); |
| 49 | + |
| 50 | + return roomsClient; |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +## Key concepts |
| 55 | + |
| 56 | +There are four operations to interact with the Azure Communication Rooms Service. |
| 57 | + |
| 58 | +## Examples |
| 59 | + |
| 60 | +### Create a new room |
| 61 | +Use the `createRoom` function to create a new Room on Azure Communciation Service. |
| 62 | + |
| 63 | +```java readme-sample-createRoomWithValidInput |
| 64 | +public void createRoomWithValidInput() { |
| 65 | + OffsetDateTime validFrom = OffsetDateTime.of(2021, 8, 1, 5, 30, 20, 10, ZoneOffset.UTC); |
| 66 | + OffsetDateTime validUntil = OffsetDateTime.of(2021, 9, 1, 5, 30, 20, 10, ZoneOffset.UTC); |
| 67 | + List<RoomParticipant> participants = new ArrayList<>(); |
| 68 | + // Add two participants |
| 69 | + participants.add(new RoomParticipant().setCommunicationIdentifier(new CommunicationUserIdentifier("<ACS User MRI identity 1>")).setRole(RoleType.ATTENDEE)); |
| 70 | + participants.add(new RoomParticipant().setCommunicationIdentifier(new CommunicationUserIdentifier("<ACS User MRI identity 2>")).setRole(RoleType.CONSUMER)); |
| 71 | + |
| 72 | + RoomsClient roomsClient = createRoomsClientWithConnectionString(); |
| 73 | + CommunicationRoom roomResult = roomsClient.createRoom(validFrom, validUntil, RoomJoinPolicy.INVITE_ONLY, participants); |
| 74 | + System.out.println("Room Id: " + roomResult.getRoomId()); |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +### Create a new open room |
| 79 | +Use the `createRoom` function to create a new Open Room on Azure Communciation Service. |
| 80 | + |
| 81 | +```java readme-sample-createOpenRoomWithValidInput |
| 82 | +public void createOpenRoomWithValidInput() { |
| 83 | + OffsetDateTime validFrom = OffsetDateTime.of(2021, 8, 1, 5, 30, 20, 10, ZoneOffset.UTC); |
| 84 | + OffsetDateTime validUntil = OffsetDateTime.of(2021, 9, 1, 5, 30, 20, 10, ZoneOffset.UTC); |
| 85 | + |
| 86 | + RoomsClient roomsClient = createRoomsClientWithConnectionString(); |
| 87 | + CommunicationRoom roomResult = roomsClient.createRoom(validFrom, validUntil, RoomJoinPolicy.INVITE_ONLY, null); |
| 88 | + System.out.println("Room Id: " + roomResult.getRoomId()); |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +### Update an existing room |
| 93 | +Use the `updateRoom` function to create a new Room on Azure Communciation Service. |
| 94 | + |
| 95 | +```java readme-sample-updateRoomWithRoomId |
| 96 | +public void updateRoomWithRoomId() { |
| 97 | + OffsetDateTime validFrom = OffsetDateTime.of(2021, 8, 1, 5, 30, 20, 10, ZoneOffset.UTC); |
| 98 | + OffsetDateTime validUntil = OffsetDateTime.of(2021, 9, 1, 5, 30, 20, 10, ZoneOffset.UTC); |
| 99 | + List<RoomParticipant> participants = new ArrayList<>(); |
| 100 | + participants.add(new RoomParticipant().setCommunicationIdentifier(new CommunicationUserIdentifier("<ACS User MRI identity 1>")).setRole(RoleType.ATTENDEE)); |
| 101 | + participants.add(new RoomParticipant().setCommunicationIdentifier(new CommunicationUserIdentifier("<ACS User MRI identity 2>")).setRole(RoleType.CONSUMER)); |
| 102 | + |
| 103 | + RoomsClient roomsClient = createRoomsClientWithConnectionString(); |
| 104 | + |
| 105 | + try { |
| 106 | + CommunicationRoom roomResult = roomsClient.updateRoom("<Room Id in String>", validFrom, validUntil, null, participants); |
| 107 | + System.out.println("Room Id: " + roomResult.getRoomId()); |
| 108 | + |
| 109 | + } catch (RuntimeException ex) { |
| 110 | + System.out.println(ex); |
| 111 | + } |
| 112 | +} |
| 113 | +``` |
| 114 | + |
| 115 | +### Get an existing room |
| 116 | +Use the `getRoom` function to get an existing Room on Azure Communciation Service. |
| 117 | + |
| 118 | +```java readme-sample-getRoomWithRoomId |
| 119 | +public void getRoomWithRoomId() { |
| 120 | + RoomsClient roomsClient = createRoomsClientWithConnectionString(); |
| 121 | + try { |
| 122 | + CommunicationRoom roomResult = roomsClient.getRoom("<Room Id in String>"); |
| 123 | + System.out.println("Room Id: " + roomResult.getRoomId()); |
| 124 | + } catch (RuntimeException ex) { |
| 125 | + System.out.println(ex); |
| 126 | + } |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +### Delete an existing room |
| 131 | +Use the `deleteRoomWithResponse` function to delete an existing Room on Azure Communciation Service. |
| 132 | + |
| 133 | +```java readme-sample-deleteRoomWithRoomId |
| 134 | +public void deleteRoomWithRoomId() { |
| 135 | + RoomsClient roomsClient = createRoomsClientWithConnectionString(); |
| 136 | + try { |
| 137 | + roomsClient.deleteRoomWithResponse("<Room Id in String>", Context.NONE); |
| 138 | + } catch (RuntimeException ex) { |
| 139 | + System.out.println(ex); |
| 140 | + } |
| 141 | +} |
| 142 | +``` |
| 143 | + |
| 144 | +### Add participants an existing room |
| 145 | +Use the `addParticipants` function to add participants to an existing Room on Azure Communciation Service. |
| 146 | + |
| 147 | +```java readme-sample-addRoomParticipantsWithRoomId |
| 148 | +public void addRoomParticipantsWithRoomId() { |
| 149 | + RoomParticipant user1 = new RoomParticipant().setCommunicationIdentifier(new CommunicationUserIdentifier("8:acs:b6372803-0c35-4ec0-833b-c19b798cef2d_0000000e-3240-55cf-9806-113a0d001dd9")).setRole(RoleType.ATTENDEE); |
| 150 | + RoomParticipant user2 = new RoomParticipant().setCommunicationIdentifier(new CommunicationUserIdentifier("8:acs:b6372803-0c35-4ec0-833b-c19b798cef2d_0000000e-3240-55cf-9806-113a0d001dd7")).setRole(RoleType.PRESENTER); |
| 151 | + RoomParticipant user3 = new RoomParticipant().setCommunicationIdentifier(new CommunicationUserIdentifier("8:acs:b6372803-0c35-4ec0-833b-c19b798cef2d_0000000e-3240-55cf-9806-113a0d001dd5")).setRole(RoleType.CONSUMER); |
| 152 | + |
| 153 | + List<RoomParticipant> participants = new ArrayList<RoomParticipant>(Arrays.asList(user1, user2, user3)); |
| 154 | + RoomsClient roomsClient = createRoomsClientWithConnectionString(); |
| 155 | + |
| 156 | + try { |
| 157 | + ParticipantsCollection roomParticipants = roomsClient.addParticipants("<Room Id>", participants); |
| 158 | + System.out.println("No. of Participants in Room: " + roomParticipants.getParticipants().size()); |
| 159 | + |
| 160 | + } catch (RuntimeException ex) { |
| 161 | + System.out.println(ex); |
| 162 | + } |
| 163 | +} |
| 164 | +``` |
| 165 | + |
| 166 | +### Remove participants an existing room |
| 167 | +Use the `removeParticipants` function to remove participants from an existing Room on Azure Communciation Service. |
| 168 | + |
| 169 | +```java readme-sample-removeRoomParticipantsWithRoomId |
| 170 | +public void removeRoomParticipantsWithRoomId() { |
| 171 | + RoomParticipant user1 = new RoomParticipant().setCommunicationIdentifier(new CommunicationUserIdentifier("8:acs:b6372803-0c35-4ec0-833b-c19b798cef2d_0000000e-3240-55cf-9806-113a0d001dd9")).setRole(RoleType.ATTENDEE); |
| 172 | + RoomParticipant user2 = new RoomParticipant().setCommunicationIdentifier(new CommunicationUserIdentifier("8:acs:b6372803-0c35-4ec0-833b-c19b798cef2d_0000000e-3240-55cf-9806-113a0d001dd7")).setRole(RoleType.PRESENTER); |
| 173 | + |
| 174 | + List<RoomParticipant> participants = new ArrayList<RoomParticipant>(Arrays.asList(user1, user2)); |
| 175 | + RoomsClient roomsClient = createRoomsClientWithConnectionString(); |
| 176 | + |
| 177 | + try { |
| 178 | + ParticipantsCollection roomParticipants = roomsClient.removeParticipants("<Room Id>", participants); |
| 179 | + System.out.println("Room Id: " + roomParticipants.getParticipants().size()); |
| 180 | + |
| 181 | + } catch (RuntimeException ex) { |
| 182 | + System.out.println(ex); |
| 183 | + } |
| 184 | +} |
| 185 | +``` |
| 186 | + |
| 187 | +## Troubleshooting |
| 188 | + |
| 189 | +1. If creating a client fails, verify if you have the right connection string. |
| 190 | +2. For room creation failures the communication error should in most case give a brief description of the issue. |
| 191 | +3. For participants update failures, make sure the participants are present in the room using the get participants. |
| 192 | + |
| 193 | +## Next steps |
| 194 | + |
| 195 | +- [Read more about Rooms in Azure Communication Services][next_steps] |
| 196 | + |
| 197 | +## Contributing |
| 198 | + |
| 199 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a [Contributor License Agreement (CLA)][cla] declaring that you have the right to, and actually do, grant us the rights to use your contribution. |
| 200 | + |
| 201 | +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. |
| 202 | + |
| 203 | +This project has adopted the [Microsoft Open Source Code of Conduct ][coc]. For more information see the [Code of Conduct FAQ ][coc_faq] or contact [[email protected]][coc_contact] with any additional questions or comments. |
| 204 | + |
| 205 | +<!-- LINKS --> |
| 206 | +[cla]: https://cla.microsoft.com |
| 207 | +[coc]: https://opensource.microsoft.com/codeofconduct/ |
| 208 | +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ |
| 209 | +[coc_contact]: mailto:[email protected] |
| 210 | +[product_docs]: https://docs.microsoft.com/azure/communication-services/ |
| 211 | +[api_documentation]: https://aka.ms/java-docs |
| 212 | + |
0 commit comments