Azure Communications Gateway Provisioning API

Cikk
03/27/2024

Az Azure Communications Gateway távközlési operátorokhoz készült Kiépítési API-ja lehetővé teszi az ügyfelek adatainak és a hozzájuk rendelt számoknak az Azure Communications Gatewaybe való kiépítését.

Az ügyfél- és számadatok Azure Communications Gatewaybe történő kiépítése kötelező, ha az Azure Communications Gatewayt a Microsoft Teams közvetlen útválasztásához és a zoom telefonfelhő-társviszony-létesítéshez használja. Ez nem kötelező a Operator Connect esetében, de lehetővé teszi egyéni SIP-fejlécek konfigurálását a számlázáshoz.

A Kiépítési API nem használható Teams Telefon Mobile-számokhoz.

Első lépések

Előfeltételek

Egy bérlő, amely üzembe helyezte az Azure Communications Gateway-alkalmazást.
A lekérdezéseket küldeni kívánt Azure Communications Gateway teljes tartományneve (FQDN) a Azure Portal erőforrásának Áttekintés lapján látható módon. Az API a tartományprovapi.<base-domain>:443 altartományának () 443-os provapi portján érhető el.
Egy olyan IP-címmel rendelkező gép, amely lehetővé teszi az API-hoz való hozzáférést az Azure Communications Gateway üzembe helyezésének részeként konfigurált engedélyezési listákban.

Hitelesítés és engedélyezés

A Provisioning API az OAuth 2.0 használatával szabályozza az erőforrásokhoz való hozzáférést. Az ügyfélalkalmazásnak érvényes hitelesítési tulajdonosi jogkivonatot kell beszereznie a Kiépítési API eléréséhez. A tulajdonosi jogkivonat azt jelzi, hogy az alkalmazás jogosult a Kiépítési API egy vagy több hatókörére (szerepkörére). Javasoljuk, hogy használja az ügyfél hitelesítő adatainak folyamatát (kiszolgálóoldali folyamathoz tervezve).

A Provisioning API-hoz a következő hatókörök érhetők el:

ProvisioningAPI.Admin: Bármely művelet meghívása az API-ban.
ProvisioningAPI.Read: Bármilyen olvasási (GET) művelet meghívása az API-ban.
ProvisioningAPI.Write: Bármilyen írási (PUT, PATCH) művelet meghívása az API-ban.
ProvisioningAPI.Delete: A törlési (DELETE) műveletek meghívásának képessége az API-ban.

Ügyfél hitelesítő adatainak beállítása:

Győződjön meg arról, hogy az alkalmazás támogatja az ügyfél hitelesítő adatainak folyamatát.

Amikor az alkalmazás jogkivonatot kér a Provisioning API-hoz, az alábbi mezőket kell használnia.

Paraméter	Feltétel	Description
Bérlő	kötelező	Az Azure Communications Gatewayt tartalmazó címtár-bérlő guid vagy tartománynév formátumban.
scope	kötelező	Az Azure Communications Gateway erőforrás-azonosítójának engedélyezési hatóköre. Az itt ismertetett ügyfél-hitelesítő adatok esetében a hatókörnek a következőnek kell lennie `https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.default`: .
client_id	kötelező	Az alkalmazáshoz rendelt alkalmazás (ügyfél) azonosítója.

A roles fogadott jogkivonatban szereplő jogcím határozza meg azokat a szerepköröket (hatóköröket), amelyekhez az ügyfélalkalmazás jogosult.
Az Azure Communications Gateway kiépítési platformjára irányuló kéréseknek rendelkezniük kell ezzel Authorization a tulajdonosi jogkivonattal.
A jogkivonatok használatára példákat az ügyfél hitelesítő adatainak folyamatdokumentációjában talál.

Az Azure Portal használatával regisztrálhatja az alkalmazást ugyanabban a bérlőben, mint az Azure Communications Gateway üzembe helyezése. Lásd: Rövid útmutató: Alkalmazás regisztrálása a Microsoft Identitásplatform – Microsoft Entra | Microsoft Learn.
Rendelje hozzá magát tulajdonosként az alkalmazásregisztrációhoz. Lásd: Alkalmazástulajdonos hozzárendelése.
Konfigurálja az alkalmazás regisztrációját úgy, hogy az alkalmazást olyan alkalmazásszerepkörökkel regisztrálja, amelyek a kiépítési API hatóköreit használják a korábban leírtak szerint.
- Lásd: Alkalmazásszerepkörök hozzárendelése alkalmazásokhoz.
- Az API, amelyhez engedélyeket kell hozzárendelnie, az AzureCommunicationsGatewaya szervezet által használt API-k alatt található.
A bérlő rendszergazdájaként engedélyezze az alkalmazás számára a hozzárendelt alkalmazásszerepkörök használatát. Lásd: Rendszergazdai hozzájárulás megadása.

A Kiépítési API szabványos Microsoft-megbízhatósági láncokat használ a biztonsági tanúsítványokhoz.

Fő fogalmak

Az Azure Communications Gateway kiépítési platformja lehetővé teszi számok kiépítését olyan szolgáltatásokhoz, mint a Microsoft Teams Direct Routing vagy a Zoom Provider Exchange. A kiépítési platform két fő erőforrással rendelkezik, amelyeket szabályozhat: a fiókokat és a számokat.

A fiókerőforrások az ügyfelek (általában egy vállalat) és a szolgáltatáskiépítés ügyfélenkénti beállításainak leírásai.
A szám típusú erőforrások egy fiókhoz tartoznak. Ismertetik a telefonszámokat (TN-eket), azokat a szolgáltatásokat, amelyeket a számok használnak (például a Microsoft Teams Közvetlen útválasztása), valamint minden további számonkénti konfigurációt.

Ha például a Microsoft Teams Közvetlen útválasztási szolgáltatást szeretné biztosítani egy ügyfélnek, a Contoso-nak, hozzon létre egy fiókerőforrást a Contoso kiépítési API-jával. A fiók a közvetlen útválasztás konfigurációját tartalmazza (például egy altartományt és a megfelelő jogkivonatokat, amelyek szükségesek az ügyfél konfigurációjának ellenőrzéséhez a Microsoft Teams által használható DNS-rekordok beállításához). Ezután számerőforrásokat kell hozzáadnia a fiókhoz, és engedélyeznie kell az egyes számokat a közvetlen útválasztáshoz. A Zoom Phone Cloud-társviszony-létesítéshez fiók- és számerőforrásokra is szükség van, de a Zoom-fiókok nem tartalmazzák ugyanazt a konfigurációt az altartományhoz és a megfelelő tokenekhez.

Fontos

Engedélyeznie kell a szolgáltatást a fiókban és a fiókban lévő számokon is.

Példák

Az alábbi példák a fiókok és számok létrehozására és kezelésére vonatkozó mintakéréseket mutatják be.

Ügyfélnek megfelelő fiók létrehozása

A PUT használatával hozzon accounts/<accountName> létre egy contoso nevű contoso fiókot a végponton, és konfiguráljon egy vagy több kommunikációs szolgáltatást a fiókhoz. Az If-None-Match fejléc használatával ellenőrizze, hogy egy ilyen nevű fiókerőforrás még nem létezik-e.

A következő példában:

A közvetlen útválasztás konfigurálva van.
A hívóazonosító szűrése engedélyezve van (ez az alapértelmezett).
Az ügyfél altartománya a következő contoso: .
A DNS-rekordok beállításához szükséges ügyfél által megadott DNS TXT értékek a és region2Token a region1Token mezőkben találhatók.

Kérés:

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"
    }
  }
}

Válasz:

HTTP/1.1 201 Created

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

A fiók részleteinek megtekintése

A GET használatával lekérheti a accounts/<accountName> fiók adatait, és ellenőrizheti, hogy a konfigurált altartomány DNS-rekordjainak beállítása sikeres volt-e (csak a Microsoft Teams Direct Routing esetében szükséges). A válasz a következő mezőket tartalmazza:

directRoutingProvisioningState, amely a DNS-rekordok állapotát jelöli. Ez a mező akkor jelenik meg, ha a lekérdezési paraméter ?status=true meg van adva a kérelemben, és csak a közvetlen útválasztás szempontjából releváns.
Az összes korábban beállított konfiguráció (vagy az alapértelmezett, ha nincs beállítva mező).
A fiók aktuális állapotát jelképező ETag. A If-Match fejlécben lévő értéket a későbbi frissítési kérelmekben is használhatja, hogy ne írja felül a másik API-felhasználók által végrehajtott módosításokat.

Kérés:

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

Válasz:

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\""
}

A fiók konfigurációjának frissítése

A fiók konfigurációjának frissítéséhez használja a accounts/<accountName> PUT parancsot a végponton. Ha meg szeretné győződni arról, hogy a frissítés nem írja felül egy másik felhasználó által végrehajtott módosítást, adjon hozzá egy If-Match fejlécet a fiók legutóbbi válaszának ETag elemével.

Kérés:

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"
    }
  }
}

Válasz:

HTTP/1.1 200 OK

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

Egy szám hozzáadása a fiókhoz

A PUT használatával a account/<accountName>/numbers/<phoneNumber> végponton adjon hozzá egy E.164-számot a fiókhoz, engedélyezzen egy vagy több kommunikációs szolgáltatást, és adjon hozzá további konfigurációt. A kiválasztott kommunikációs szolgáltatásokat is konfigurálni kell a fiókon. Az If-None-Match fejléc használatával ellenőrizze, hogy egy ilyen számmal rendelkező számerőforrás még nem létezik-e.

A következő példában:

A szám +123451.
A közvetlen útválasztás engedélyezve van.
customSipHeader meghatározza, hogy az Azure Communications Gatewaynek hozzá kell adnia egy fejlécet a exampleHeaderContents hálózatra küldött üzenetekhez.

Fontos

Az egyéni fejléc neve a Kiépítési API Azure Portal konfigurációjában van beállítva. Minden üzenet esetében ugyanaz.

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"
  }
}

Válasz:

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\""
}

Szám konfigurációjának frissítése

Egy szám konfigurációjának frissítéséhez használja a PUT parancsot a account/<accountName>/numbers/<phoneNumber> végponton. Annak érdekében, hogy a frissítés ne írja felül egy másik felhasználó által végrehajtott módosítást, adjon hozzá egy If-Match fejlécet a számra adott legutóbbi válasz ETagjével.

Kérés:

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"
  }
}

Válasz:

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\""
}

Egyszerre több szám hozzáadása vagy frissítése

A végponton a account/<accountName>/numbers:batch POST használatával egyszerre legfeljebb 100 számot adhat hozzá a fiókhoz. Ez a végpont a fiókban lévő számok frissítésére is használható. A számok tranzakciósan lesznek hozzáadva: ha valamelyik frissítés sikertelen, az összes frissítés sikertelen lesz.

Kérés:

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"
        }
      }
    }
  ]
}

Válasz:

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\""
    }
  ]
}

A fiók összes számának lekérése

Használja a GET parancsot a végponton a account/<accountName>/numbers fiókban lévő összes szám lekéréséhez a konfigurációjukkal. A és maxpagesize a skip lekérdezési paraméterekkel szabályozhatja a válasz lapszámozását. Ha több számot kell visszaadni, a válasz egy nextLink mezőt fog tartalmazni, amely azt az URL-címet jelzi, amely az eredmények következő oldalának lekéréséhez kérhető.

Kérés:

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

Válasz:

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"
}

Hibaelhárítás

A Teams közvetlen útválasztása nem működik a fiókokban lévő számok esetében.
- Ellenőrizze, hogy a DNS-jogkivonat érvényesítve lett-e. Ehhez küldjön egy GET-t a fiókhoz a ?status=true lekérdezési paraméterrel, és ellenőrizze, hogy a directRoutingProvisioningState értéke megegyezik-e subdomainStatus a következővel Provisioned: .
Konfiguráltam egy számot a közvetlen útválasztás/nagyítás használatára, de úgy tűnik, hogy nem működik.
- Ellenőrizze, hogy a fiók konfigurálva van-e a közvetlen útválasztás/nagyítás használatára, és hogy a számon engedélyezve van-e ez a funkció.
Kapcsolatba léphetek az API-val, de több kérés után a kapcsolatok időtúllépésnek indulnak.
- A kiépítési API sebességkorlátos. Részletekért tekintse meg az Azure Communications Gateway korlátait, kvótáit és korlátozásait ismertető cikket. A sebesség korlátozásának elkerülése érdekében terjesszen ki a kérések között, vagy használja a kötegelt végpontot. A sebességkorlát idővel túllépi az időkorlátot, és csatlakozhat.

Következő lépések

Integrálás az Azure Communications Gateway Provisioning API-val.

Azure Communications Gateway Provisioning API

Első lépések

Előfeltételek

Hitelesítés és engedélyezés

Fő fogalmak

Példák

Ügyfélnek megfelelő fiók létrehozása

A fiók részleteinek megtekintése

A fiók konfigurációjának frissítése

Egy szám hozzáadása a fiókhoz

Szám konfigurációjának frissítése

Egyszerre több szám hozzáadása vagy frissítése

A fiók összes számának lekérése

Hibaelhárítás

Következő lépések

További források