{ "swagger": "2.0", "info": { "title": "Azure Communication Services Management API", "version": "2020-08-20", "description": "REST API for Azure Communication Services" }, "consumes": [ "application/json" ], "produces": [ "application/json" ], "host": "management.azure.com", "schemes": [ "https" ], "securityDefinitions": { "azure_auth": { "type": "oauth2", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "flow": "implicit", "description": "Azure Active Directory OAuth2 Flow", "scopes": { "user_impersonation": "impersonate your user account" } } }, "paths": { "/providers/Microsoft.Communication/operations": { "get": { "description": "Lists all of the available REST API operations of the Microsoft.Communication provider.", "operationId": "Operations_List", "summary": "List Operations", "tags": [ "Operations" ], "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "Success. The response describes the list of operations.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/OperationListResult" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-pageable": { "nextLinkName": "nextLink" } } }, "/subscriptions/{subscriptionId}/providers/Microsoft.Communication/checkNameAvailability": { "post": { "description": "Checks that the CommunicationService name is valid and is not already in use.", "operationId": "CommunicationService_CheckNameAvailability", "summary": "Check Name Availability", "tags": [ "CommunicationService" ], "parameters": [ { "name": "nameAvailabilityParameters", "in": "body", "schema": { "$ref": "#/definitions/NameAvailabilityParameters" }, "description": "Parameters supplied to the operation." }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" } ], "consumes": [ "application/json" ], "responses": { "200": { "description": "Success. The response describes the name availability.", "schema": { "$ref": "#/definitions/NameAvailability" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-examples": { "Check name availability available": { "$ref": "./examples/checkNameAvailabilityAvailable.json" }, "Check name availability unavailable": { "$ref": "./examples/checkNameAvailabilityUnavailable.json" } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Communication/communicationServices/{communicationServiceName}/linkNotificationHub": { "post": { "description": "Links an Azure Notification Hub to this communication service.", "operationId": "CommunicationService_LinkNotificationHub", "summary": "Link Notification Hub", "tags": [ "CommunicationService" ], "parameters": [ { "name": "linkNotificationHubParameters", "in": "body", "schema": { "$ref": "#/definitions/LinkNotificationHubParameters" }, "description": "Parameters supplied to the operation." }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "#/parameters/CommunicationServiceName" } ], "consumes": [ "application/json" ], "responses": { "200": { "description": "Success. The notification hub has been linked.", "schema": { "$ref": "#/definitions/LinkedNotificationHub" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-examples": { "Link notification hub": { "$ref": "./examples/linkNotificationHub.json" } } } }, "/subscriptions/{subscriptionId}/providers/Microsoft.Communication/communicationServices": { "get": { "description": "Handles requests to list all resources in a subscription.", "operationId": "CommunicationService_ListBySubscription", "summary": "List By Subscription", "tags": [ "CommunicationService" ], "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" } ], "responses": { "200": { "description": "Success. The response describes the list of CommunicationServices in the subscription.", "schema": { "$ref": "#/definitions/CommunicationServiceResourceList" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-pageable": { "nextLinkName": "nextLink" }, "x-ms-examples": { "List by subscription": { "$ref": "./examples/listBySubscription.json" } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Communication/communicationServices": { "get": { "description": "Handles requests to list all resources in a resource group.", "operationId": "CommunicationService_ListByResourceGroup", "summary": "List By Resource Group", "tags": [ "CommunicationService" ], "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" } ], "responses": { "200": { "description": "Success. The response describes the list of CommunicationServices in a resourceGroup.", "schema": { "$ref": "#/definitions/CommunicationServiceResourceList" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink" }, "produces": [ "application/json" ], "x-ms-examples": { "List by resource group": { "$ref": "./examples/listByResourceGroup.json" } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Communication/communicationServices/{communicationServiceName}": { "patch": { "description": "Operation to update an existing CommunicationService.", "operationId": "CommunicationService_Update", "summary": "Update", "tags": [ "CommunicationService" ], "parameters": [ { "name": "parameters", "in": "body", "description": "Parameters for the update operation", "required": false, "schema": { "$ref": "#/definitions/CommunicationServiceResource" } }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "#/parameters/CommunicationServiceName" } ], "responses": { "200": { "description": "The update request was successful", "schema": { "$ref": "#/definitions/CommunicationServiceResource" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-examples": { "Update resource": { "$ref": "./examples/update.json" } } }, "get": { "description": "Get the CommunicationService and its properties.", "operationId": "CommunicationService_Get", "summary": "Get", "tags": [ "CommunicationService" ], "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "#/parameters/CommunicationServiceName" } ], "responses": { "200": { "description": "Success. The response describe the corresponding CommunicationService service.", "schema": { "$ref": "#/definitions/CommunicationServiceResource" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-examples": { "Get resource": { "$ref": "./examples/get.json" } } }, "put": { "description": "Create a new CommunicationService or update an existing CommunicationService.", "operationId": "CommunicationService_CreateOrUpdate", "summary": "Create Or Update", "tags": [ "CommunicationService" ], "parameters": [ { "name": "parameters", "in": "body", "description": "Parameters for the create or update operation", "required": false, "schema": { "$ref": "#/definitions/CommunicationServiceResource" } }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "#/parameters/CommunicationServiceName" } ], "consumes": [ "application/json" ], "responses": { "200": { "description": "The create or update request was completed successfully", "schema": { "$ref": "#/definitions/CommunicationServiceResource" } }, "201": { "description": "The create or update request was accepted", "headers": { "Azure-AsyncOperation": { "description": "URL to query for status of the operation.", "type": "string" } }, "schema": { "$ref": "#/definitions/CommunicationServiceResource" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "azure-async-operation" }, "x-ms-examples": { "Create or update resource": { "$ref": "./examples/createOrUpdate.json" } } }, "delete": { "description": "Operation to delete a CommunicationService.", "operationId": "CommunicationService_Delete", "summary": "Delete", "tags": [ "CommunicationService" ], "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "#/parameters/CommunicationServiceName" } ], "responses": { "200": { "description": "The delete operation was successful." }, "202": { "description": "The delete operation is being performed in the background.", "headers": { "location": { "description": "URL to query for status of the operation.", "type": "string" } } }, "204": { "description": "The resource did not exist." }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "x-ms-long-running-operation": true, "x-ms-long-running-operation-options": { "final-state-via": "location" }, "x-ms-examples": { "Delete resource": { "$ref": "./examples/delete.json" } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Communication/communicationServices/{communicationServiceName}/listKeys": { "post": { "description": "Get the access keys of the CommunicationService resource.", "operationId": "CommunicationService_ListKeys", "summary": "List Keys", "tags": [ "CommunicationService" ], "parameters": [ { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "#/parameters/CommunicationServiceName" } ], "responses": { "200": { "description": "Success. The response describes CommunicationService access keys.", "schema": { "$ref": "#/definitions/CommunicationServiceKeys" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "produces": [ "application/json" ], "x-ms-examples": { "List keys": { "$ref": "./examples/listKeys.json" } } } }, "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Communication/communicationServices/{communicationServiceName}/regenerateKey": { "post": { "description": "Regenerate CommunicationService access key. PrimaryKey and SecondaryKey cannot be regenerated at the same time.", "operationId": "CommunicationService_RegenerateKey", "summary": "Regenerate Key", "tags": [ "CommunicationService" ], "parameters": [ { "name": "parameters", "in": "body", "description": "Parameter that describes the Regenerate Key Operation.", "required": true, "schema": { "$ref": "#/definitions/RegenerateKeyParameters" } }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ApiVersionParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/SubscriptionIdParameter" }, { "$ref": "../../../../../../common-types/resource-management/v1/types.json#/parameters/ResourceGroupNameParameter" }, { "$ref": "#/parameters/CommunicationServiceName" } ], "responses": { "200": { "description": "Created. The response contains the new key.", "schema": { "$ref": "#/definitions/CommunicationServiceKeys" } }, "default": { "description": "Error response describing why the operation failed.", "schema": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/ErrorResponse" } } }, "consumes": [ "application/json" ], "produces": [ "application/json" ], "x-ms-examples": { "Regenerate key": { "$ref": "./examples/regenerateKey.json" } } } } }, "definitions": { "NameAvailabilityParameters": { "description": "Data POST-ed to the nameAvailability action", "required": [ "type", "name" ], "type": "object", "properties": { "type": { "description": "The resource type. Should be always \"Microsoft.Communication/CommunicationServices\".", "type": "string" }, "name": { "description": "The CommunicationService name to validate. e.g.\"my-CommunicationService-name-here\"", "type": "string" } } }, "NameAvailability": { "description": "Result of the request to check name availability. It contains a flag and possible reason of failure.", "type": "object", "properties": { "nameAvailable": { "description": "Indicates whether the name is available or not.", "type": "boolean" }, "reason": { "description": "The reason of the availability. Required if name is not available.", "type": "string" }, "message": { "description": "The message of the operation.", "type": "string" } } }, "LinkNotificationHubParameters": { "description": "Description of an Azure Notification Hub to link to the communication service", "required": [ "resourceId", "connectionString" ], "type": "object", "properties": { "resourceId": { "description": "The resource ID of the notification hub", "type": "string" }, "connectionString": { "description": "Connection string for the notification hub", "type": "string" } } }, "LinkedNotificationHub": { "description": "A notification hub that has been linked to the communication service", "type": "object", "properties": { "resourceId": { "description": "The resource ID of the notification hub", "type": "string" } } }, "CommunicationServiceResourceList": { "description": "Object that includes an array of CommunicationServices and a possible link for next set.", "type": "object", "properties": { "value": { "description": "List of CommunicationService", "type": "array", "items": { "$ref": "#/definitions/CommunicationServiceResource" } }, "nextLink": { "description": "The URL the client should use to fetch the next page (per server side paging).\r\nIt's null for now, added for future use.", "type": "string" } } }, "CommunicationServiceResource": { "description": "A class representing a CommunicationService resource.", "type": "object", "allOf": [ { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/Resource" }, { "$ref": "#/definitions/LocationResource" }, { "$ref": "#/definitions/TaggedResource" } ], "properties": { "properties": { "$ref": "#/definitions/CommunicationServiceProperties", "description": "The properties of the service.", "x-ms-client-flatten": true }, "systemData": { "$ref": "../../../../../../common-types/resource-management/v2/types.json#/definitions/systemData" } } }, "LocationResource": { "description": "An ARM resource with its own location (not a global or an inherited location).", "type": "object", "properties": { "location": { "description": "The Azure location where the CommunicationService is running.", "type": "string", "x-ms-mutability": [ "create", "read" ] } } }, "TaggedResource": { "description": "An ARM resource with that can accept tags", "type": "object", "properties": { "tags": { "description": "Tags of the service which is a list of key value pairs that describe the resource.", "type": "object", "additionalProperties": { "type": "string" }, "x-ms-mutability": [ "read", "create", "update" ] } } }, "CommunicationServiceProperties": { "description": "A class that describes the properties of the CommunicationService.", "required": [ "dataLocation" ], "type": "object", "properties": { "provisioningState": { "description": "Provisioning state of the resource.", "enum": [ "Unknown", "Succeeded", "Failed", "Canceled", "Running", "Creating", "Updating", "Deleting", "Moving" ], "type": "string", "readOnly": true, "x-ms-enum": { "name": "ProvisioningState", "modelAsString": true } }, "hostName": { "description": "FQDN of the CommunicationService instance.", "type": "string", "readOnly": true }, "dataLocation": { "description": "The location where the communication service stores its data at rest.", "type": "string", "x-ms-mutability": [ "create", "read" ] }, "notificationHubId": { "description": "Resource ID of an Azure Notification Hub linked to this resource.", "type": "string", "readOnly": true }, "version": { "description": "Version of the CommunicationService resource. Probably you need the same or higher version of client SDKs.", "type": "string", "readOnly": true }, "immutableResourceId": { "description": "The immutable resource Id of the communication service.", "type": "string", "readOnly": true } } }, "CommunicationServiceKeys": { "description": "A class representing the access keys of a CommunicationService.", "type": "object", "properties": { "primaryKey": { "description": "The primary access key.", "type": "string" }, "secondaryKey": { "description": "The secondary access key.", "type": "string" }, "primaryConnectionString": { "description": "CommunicationService connection string constructed via the primaryKey", "type": "string" }, "secondaryConnectionString": { "description": "CommunicationService connection string constructed via the secondaryKey", "type": "string" } } }, "RegenerateKeyParameters": { "description": "Parameters describes the request to regenerate access keys", "type": "object", "properties": { "keyType": { "description": "The keyType to regenerate. Must be either 'primary' or 'secondary'(case-insensitive).", "enum": [ "Primary", "Secondary" ], "type": "string", "x-ms-enum": { "name": "KeyType", "modelAsString": false } } } } }, "parameters": { "CommunicationServiceName": { "name": "communicationServiceName", "in": "path", "description": "The name of the CommunicationService resource.", "pattern": "^[-\\w]+$", "minLength": 1, "maxLength": 63, "required": true, "type": "string", "x-ms-parameter-location": "method" } } }