API d’approvisionnement azure Communications Gateway

Article
03/27/2024

L’API d’approvisionnement d’Azure Communications Gateway pour les opérateurs de télécommunications vous permet de provisionner les détails de vos clients et les numéros qui leur sont attribués dans Azure Communications Gateway.

L’approvisionnement des informations sur les clients et les numéros dans Azure Communications Gateway est obligatoire lors de l’utilisation d’Azure Communications Gateway pour le routage direct Microsoft Teams et le peering cloud zoom phone. Il est facultatif pour Operator Connect, mais vous permet de configurer un en-tête SIP personnalisé pour la facturation.

Vous ne pouvez pas utiliser l’API d’approvisionnement pour Téléphonie Teams numéros mobiles.

Prise en main

Prérequis

Un locataire avec l’application Azure Communications Gateway déployée.
Nom de domaine complet (FQDN) de la passerelle de communications Azure vers laquelle vous souhaitez envoyer des requêtes, tel qu’affiché dans la page Vue d’ensemble de la ressource dans le Portail Azure. L’API est disponible sur le port 443 du provapi sous-domaine de ce domaine (provapi.<base-domain>:443).
Machine avec une adresse IP qui autorise l’accès à l’API, telle qu’elle est configurée dans une liste d’autorisation dans le cadre du déploiement d’Azure Communications Gateway.

Authentification et autorisation

L’API Provisionnement utilise OAuth 2.0 pour contrôler l’accès aux ressources. L’application cliente doit obtenir un jeton du porteur d’authentification valide pour accéder à l’API d’approvisionnement. Le jeton du porteur indique que l’application est autorisée pour une ou plusieurs étendues (rôles) pour l’API d’approvisionnement. Nous vous recommandons d’utiliser le flux d’informations d’identification du client (conçu pour un processus côté serveur).

Les étendues suivantes sont disponibles pour l’API d’approvisionnement :

ProvisioningAPI.Admin: possibilité d’appeler n’importe quelle opération sur l’API.
ProvisioningAPI.Read: possibilité d’appeler n’importe quelle opération de lecture (GET) sur l’API.
ProvisioningAPI.Write: possibilité d’appeler n’importe quelle opération d’écriture (PUT, PATCH) sur l’API.
ProvisioningAPI.Delete: possibilité d’appeler n’importe quelle opération de suppression (DELETE) sur l’API.

Pour configurer un flux d’informations d’identification client :

Vérifiez que votre application peut prendre en charge le flux d’informations d’identification du client.

Lorsque votre application demande un jeton pour l’API d’approvisionnement, elle doit utiliser les champs suivants.

Paramètre	Condition	Description
tenant	Obligatoire	Locataire d’annuaire contenant la passerelle de communications Azure, sous forme de guid ou de nom de domaine.
scope	Obligatoire	Étendue de l’autorisation par rapport à l’ID de ressource Azure Communications Gateway. Pour le flux d’informations d’identification du client décrit ici, l’étendue doit être `https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.default`.
client_id	obligatoire	ID d’application (client) affecté à votre application.

La roles revendication dans le jeton reçu spécifie les rôles (étendues) auxquels l’application cliente est autorisée à accéder.
Les demandes adressées à la plateforme d’approvisionnement Azure Communications Gateway doivent avoir un Authorization en-tête avec ce jeton du porteur.
Consultez la documentation relative au flux d’informations d’identification du client pour obtenir des exemples d’utilisation de jetons.

Utilisez le Portail Azure pour inscrire l’application dans le même locataire que votre déploiement Azure Communications Gateway. Consultez Démarrage rapide : Inscrire une application dans le Plateforme d'identités Microsoft - Microsoft Entra | Microsoft Learn.
Attribuez-vous en tant que propriétaire pour l’inscription de l’application. Consultez Affecter un propriétaire d’application.
Configurez l’inscription d’application créée en inscrivant l’application avec des rôles d’application qui utilisent les étendues de l’API De provisionnement, comme décrit précédemment.
- Consultez Attribuer des rôles d’application aux applications.
- L’API pour laquelle vous devez attribuer des autorisations est AzureCommunicationsGateway, répertoriée sous API que mon organization utilise.
En tant qu’administrateur du locataire, autorisez l’application à utiliser les rôles d’application que vous avez attribués. Consultez Accorder le consentement de l’administrateur.

L’API provisionnement utilise des chaînes d’approbation Microsoft standard pour les certificats de sécurité.

Concepts clés

La plateforme d’approvisionnement Azure Communications Gateway vous permet de provisionner des numéros à utiliser avec des services tels que le routage direct Microsoft Teams ou le zoom provider Exchange. La plateforme d’approvisionnement a deux ressources clés que vous pouvez contrôler : les comptes et les nombres.

Les ressources de compte sont des descriptions de vos clients (généralement, une entreprise) et des paramètres par client pour l’approvisionnement de services.
Les ressources numériques appartiennent à un compte. Ils décrivent les numéros de téléphone (TN), les services utilisés par les numéros (par exemple, routage direct Microsoft Teams) et toute configuration supplémentaire par numéro.

Par exemple, pour fournir le service de routage direct Microsoft Teams à un client, Contoso, créez une ressource de compte avec l’API d’approvisionnement pour Contoso. Le compte contient la configuration du routage direct (par exemple, un sous-domaine et les jetons correspondants, nécessaires à la configuration des enregistrements DNS que Microsoft Teams peut utiliser pour valider la configuration du client). Vous devez ensuite ajouter des ressources numériques au compte et activer chaque nombre pour le routage direct. Zoom Phone Cloud Peering nécessite également des ressources de compte et de numéro, mais les comptes Zoom ne contiennent pas la même configuration pour le sous-domaine et les jetons correspondants.

Important

Vous devez activer le service sur le compte et les numéros du compte.

Exemples

Les exemples suivants montrent des exemples de demandes de création et de gestion de comptes et de numéros.

Créer un compte pour représenter un client

Utilisez PUT sur le accounts/<accountName> point de terminaison pour créer un compte nommé contoso pour le client Contoso et configurer un ou plusieurs services de communication pour le compte. Utilisez un en-tête If-None-Match pour vérifier qu’une ressource de compte portant ce nom n’existe pas déjà.

Dans l’exemple suivant :

Le routage direct est configuré.
Le filtrage de l’ID de l’appelant est activé (valeur par défaut).
Le sous-domaine du client est contoso.
Les valeurs TXT DNS fournies par le client nécessaires à la configuration des enregistrements DNS se trouvent dans les region1Token champs et region2Token .

Demande :

PUT /accounts/contoso?api-version=2023-10-01 HTTP/1.1

If-None-Match: *
Content-Type: application/json

{
  "directRouting": {
    "callScreening": true,
    "subdomain": "contoso",
    "subdomainTokens": {
      "region1Token": "exampleToken1",
      "region2Token": "exampleToken2"
    }
  }
}

Réponse :

HTTP/1.1 201 Created

{
  "name": "contoso",
  "details": {
    "directRouting": {
      "callScreening": true,
      "subdomain": "contoso",
      "subdomainTokens": {
        "region1Token": "exampleToken1",
        "region2Token": "exampleToken2"
      }
    }
  },
  "etag": "\"0000241f-0000-0700-0000-650845140000\""
}

Afficher les détails du compte

Utilisez GET sur le accounts/<accountName> point de terminaison pour obtenir les détails du compte et case activée que la configuration des enregistrements DNS pour le sous-domaine configuré a réussi (nécessaire uniquement pour le routage direct Microsoft Teams). La réponse inclut les champs suivants :

directRoutingProvisioningState, représentant l’état des enregistrements DNS. Ce champ est inclus lorsque le paramètre ?status=true de requête est spécifié dans la requête et n’est pertinent que pour le routage direct.
Toute la configuration précédemment définie (ou la valeur par défaut, si aucun champ n’a été défini).
ETag représentant l’état actuel du compte. Vous pouvez utiliser la valeur dans un en-tête If-Match sur les demandes de mise à jour suivantes pour vous assurer que vous ne remplacez pas les modifications apportées par d’autres utilisateurs d’API.

Demande :

GET /accounts/contoso?api-version=2023-10-01&status=true HTTP/1.1

Réponse :

HTTP/1.1 200 OK

ETag: "0000241f-0000-0700-0000-650845140000"

{
  "directRoutingProvisioningState": {
    "subdomainStatus": "Provisioned"
  },
  "name": "contoso",
  "details": {
    "directRouting": {
      "callScreening": true,
      "subdomain": "contoso",
      "subdomainTokens": {
        "region1Token": "exampleToken1",
        "region2Token": "exampleToken2"
      }
    }
  },
  "etag": "\"0000241f-0000-0700-0000-650845140000\""
}

Mettre à jour la configuration du compte

Utilisez PUT sur le point de accounts/<accountName> terminaison pour mettre à jour la configuration du compte. Pour vous assurer que la mise à jour ne remplace pas une modification apportée par un autre utilisateur, ajoutez un en-tête If-Match avec l’ETag de la réponse la plus récente pour le compte.

Demande :

PUT /accounts/contoso?api-version=2023-10-01 HTTP/1.1

If-Match: "0000241f-0000-0700-0000-650845140000"
Content-Type: application/json

{
  "directRouting": {
    "callScreening": false,
    "subdomain": "contoso",
    "subdomainTokens": {
      "region1Token": "exampleTokenNew1",
      "region2Token": "exampleTokenNew2"
    }
  }
}

Réponse :

HTTP/1.1 200 OK

{
  "name": "contoso",
  "details": {
    "directRouting": {
      "callScreening": false,
      "subdomain": "contoso",
      "subdomainTokens": {
        "region1Token": "exampleTokenNew1",
        "region2Token": "exampleTokenNew2"
      }
    }
  },
  "etag": "\"0000351f-0000-0700-0000-65084a810000\""
}

Ajouter un numéro au compte

Utilisez PUT sur le account/<accountName>/numbers/<phoneNumber> point de terminaison pour ajouter un numéro E.164 au compte, activer un ou plusieurs services de communication et ajouter toute configuration supplémentaire. Les services de communication choisis doivent également être configurés sur le compte. Utilisez un en-tête If-None-Match pour vérifier qu’une ressource numérique avec ce numéro n’existe pas déjà.

Dans l’exemple suivant :

Le nombre est +123451.
Le routage direct est activé.
customSipHeader spécifie qu’Azure Communications Gateway doit ajouter un en-tête avec la valeur exampleHeaderContents aux messages envoyés à votre réseau.

Important

Le nom de l’en-tête personnalisé est défini dans la configuration Portail Azure de l’API De provisionnement. Il en est de même pour tous les messages.

PUT /account/contoso/numbers/%2B123451?api-version=2023-10-01 HTTP/1.1

If-None-Match: *
Content-Type: application/json

{
  "services": {
    "teamsDrEnabled": true,
    "teamsOcEnabled": false,
    "zoomEnabled": false
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Réponse :

HTTP/1.1 201 Created

{
  "phoneNumber": "+123451",
  "accountName": "contoso",
  "details": {
    "services": {
      "teamsDrEnabled": true,
      "teamsOcEnabled": false,
      "zoomEnabled": false
    },
    "configuration": {
      "customSipHeader": "exampleHeaderContents"
    }
  },
  "etag": "\"19004107-0000-0700-0000-65084ad60000\""
}

Mettre à jour la configuration d’un nombre

Utilisez PUT sur le point de terminaison pour mettre à jour la account/<accountName>/numbers/<phoneNumber> configuration d’un nombre. Pour vous assurer que la mise à jour ne remplace pas une modification apportée par un autre utilisateur, ajoutez un en-tête If-Match avec l’ETag à partir de la réponse la plus récente pour le nombre.

Demande :

PUT /account/contoso/numbers/%2B123451?api-version=2023-10-01 HTTP/1.1

If-Match: "19004107-0000-0700-0000-65084ad60000"
Content-Type: application/json

{
  "services": {
    "teamsDrEnabled": true,
    "teamsOcEnabled": false,
    "zoomEnabled": false
  },
  "configuration": {
    "customSipHeader": "exampleNewHeader"
  }
}

Réponse :

HTTP/1.1 200 OK

{
  "phoneNumber": "+123451",
  "accountName": "contoso",
  "details": {
    "services": {
      "teamsDrEnabled": true,
      "teamsOcEnabled": false,
      "zoomEnabled": false
    },
    "configuration": {
      "customSipHeader": "exampleNewHeader"
    }
  },
  "etag": "\"19007a0a-0000-0700-0000-65084ca00000\""
}

Ajouter ou mettre à jour plusieurs nombres à la fois

Utilisez POST sur le point de account/<accountName>/numbers:batch terminaison pour ajouter jusqu’à 100 numéros au compte à la fois. Ce point de terminaison peut également être utilisé pour mettre à jour des numéros dans le compte. Les numéros sont ajoutés par transaction : si une mise à jour échoue, toutes les mises à jour échouent.

Demande :

POST /account/contoso/numbers:batch?api-version=2023-10-01 HTTP/1.1

Content-Type: application/json

{
  "numbers": [
    {
      "phoneNumber": "+123452",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleHeaderContents"
        }
      }
    },
    {
      "phoneNumber": "+123453",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleHeaderContents"
        }
      }
    }
  ]
}

Réponse :

HTTP/1.1 200 OK

{
  "numbers": [
    {
      "phoneNumber": "+123452",
      "accountName": "contoso",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleHeaderContents"
        }
      },
      "etag": "\"19002b0c-0000-0700-0000-65084d900000\""
    },
    {
      "phoneNumber": "+123453",
      "accountName": "contoso",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleHeaderContents"
        }
      },
      "etag": "\"19002c0c-0000-0700-0000-65084d900000\""
    }
  ]
}

Obtenir tous les nombres dans le compte

Utilisez GET sur le point de account/<accountName>/numbers terminaison pour obtenir tous les numéros du compte avec leur configuration. Utilisez les paramètres de skip requête et maxpagesize pour contrôler la façon dont la réponse est paginé. Si d’autres nombres doivent être retournés, la réponse contient un nextLink champ indiquant l’URL à demander pour obtenir la page de résultats suivante.

Demande :

GET /account/contoso/numbers?api-version=2023-10-01&skip=0&maxpagesize=2 HTTP/1.1

Réponse :

HTTP/1.1 200 OK

{
  "value": [
    {
      "phoneNumber": "+123451",
      "accountName": "contoso",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleNewHeader"
        }
      },
      "etag": "\"19007a0a-0000-0700-0000-65084ca00000\""
    },
    {
      "phoneNumber": "+123452",
      "accountName": "contoso",
      "details": {
        "services": {
          "teamsDrEnabled": true,
          "teamsOcEnabled": false,
          "zoomEnabled": false
        },
        "configuration": {
          "customSipHeader": "exampleHeaderContents"
        }
      },
      "etag": "\"19002b0c-0000-0700-0000-65084d900000\""
    }
  ],
  "nextLink": "https://<api-fqdn>/account/contoso/numbers?api-version=2023-10-01&skip=2&maxpagesize=2"
}

Dépannage

Le routage direct Teams ne fonctionne pas pour les nombres sur un compte.
- Vérifiez que le jeton DNS a été validé en envoyant un GET sur le compte avec le ?status=true paramètre de requête, puis vérifiez que le directRoutingProvisioningState a subdomainStatus égal à Provisioned.
J’ai configuré un nombre pour utiliser le routage direct/zoom, mais il ne semble pas fonctionner.
- Vérifiez que le compte est configuré pour utiliser le routage direct/zoom et que cette fonctionnalité spécifique est activée pour le nombre.
Je peux contacter l’API, mais après avoir effectué plusieurs demandes, mes connexions commencent à expirer.
- L’API d’approvisionnement est limitée au débit. Pour plus d’informations , consultez Limites, quotas et restrictions d’Azure Communications Gateway . Espacez vos demandes ou utilisez le point de terminaison de lot pour éviter d’être limité au débit. La limite de débit expirera et vous pourrez vous connecter.

Étapes suivantes

Commencez à intégrer à l’API d’approvisionnement azure Communications Gateway.

API d’approvisionnement azure Communications Gateway

Prise en main

Prérequis

Authentification et autorisation

Concepts clés

Exemples

Créer un compte pour représenter un client

Afficher les détails du compte

Mettre à jour la configuration du compte

Ajouter un numéro au compte

Mettre à jour la configuration d’un nombre

Ajouter ou mettre à jour plusieurs nombres à la fois

Obtenir tous les nombres dans le compte

Dépannage

Étapes suivantes

Ressources supplémentaires