Interfejs API aprowizacji usługi Azure Communications Gateway

Artykuł
04/01/2024

Interfejs API aprowizacji usługi Azure Communications Gateway dla operatorów telekomunikacyjnych umożliwia aprowizowanie szczegółów klientów i numerów przypisanych do nich w usłudze Azure Communications Gateway.

Aprowizowanie informacji o kliencie i numerze w usłudze Azure Communications Gateway jest obowiązkowe w przypadku korzystania z usługi Azure Communications Gateway dla routingu bezpośredniego w usłudze Microsoft Teams i komunikacji równorzędnej zoom phone Cloud Peering Jest to opcjonalne w przypadku połączenia operatorów, ale umożliwia skonfigurowanie niestandardowego nagłówka SIP na potrzeby rozliczeń.

Nie można użyć interfejsu API aprowizacji dla Telefon w Teams numerów telefonów komórkowych.

Wprowadzenie

Wymagania wstępne

Dzierżawa z wdrożona aplikacją usługi Azure Communications Gateway.
W pełni kwalifikowana nazwa domeny (FQDN) dla usługi Azure Communications Gateway, do której chcesz wysyłać zapytania, jak pokazano na stronie Przegląd zasobu w Azure Portal. Interfejs API jest dostępny na porcie 443 provapi poddomeny tej domeny (provapi.<base-domain>:443).
Maszyna z adresem IP, który umożliwia dostęp do interfejsu API zgodnie z konfiguracją na liście dozwolonych w ramach wdrażania usługi Azure Communications Gateway.

Uwierzytelnianie i autoryzacja

Interfejs API aprowizacji używa protokołu OAuth 2.0 do kontrolowania dostępu do zasobów. Aplikacja kliencka musi uzyskać prawidłowy token elementu nośnego uwierzytelniania w celu uzyskania dostępu do interfejsu API aprowizacji. Token elementu nośnego wskazuje, że aplikacja jest autoryzowana dla co najmniej jednego zakresu (ról) dla interfejsu API aprowizacji. Zalecamy użycie przepływu poświadczeń klienta (przeznaczonego do przetwarzania po stronie serwera).

Dla interfejsu API aprowizacji są dostępne następujące zakresy:

ProvisioningAPI.Admin: Możliwość wywoływania dowolnej operacji w interfejsie API.
ProvisioningAPI.Read: Możliwość wywołania dowolnej operacji odczytu (GET) w interfejsie API.
ProvisioningAPI.Write: Możliwość wywołania dowolnej operacji zapisu (PUT, PATCH) w interfejsie API.
ProvisioningAPI.Delete: Możliwość wywołania dowolnej operacji usuwania (DELETE) w interfejsie API.

Aby skonfigurować przepływ poświadczeń klienta:

Upewnij się, że aplikacja może obsługiwać przepływ poświadczeń klienta.

Gdy aplikacja żąda tokenu dla interfejsu API aprowizacji, musi użyć następujących pól.

Parametr	Warunek	Opis
Dzierżawy	wymagane	Dzierżawa katalogu zawierająca usługę Azure Communications Gateway w postaci identyfikatora GUID lub nazwy domeny.
scope	wymagane	Zakres autoryzacji względem identyfikatora zasobu usługi Azure Communications Gateway. W przypadku przepływu poświadczeń klienta opisanego tutaj zakres powinien mieć wartość `https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.default`.
client_id	wymagane	Identyfikator aplikacji (klienta) przypisany do aplikacji.

Oświadczenie roles w otrzymany token określa role (zakresy), do których aplikacja kliencka ma uprawnienia dostępu.
Żądania do platformy aprowizacji usługi Azure Communications Gateway muszą mieć Authorization nagłówek z tym tokenem elementu nośnego.
Zapoznaj się z dokumentacją przepływu poświadczeń klienta , aby zapoznać się z przykładami używania tokenów.

Użyj Azure Portal, aby zarejestrować aplikację w tej samej dzierżawie co wdrożenie usługi Azure Communications Gateway. Zobacz Szybki start: rejestrowanie aplikacji w Platforma tożsamości Microsoft — Microsoft Entra | Microsoft Learn.
Przypisz siebie jako właściciela rejestracji aplikacji. Zobacz Przypisywanie właściciela aplikacji.
Skonfiguruj rejestrację aplikacji utworzoną przez zarejestrowanie aplikacji z rolami aplikacji, które używają zakresów dla interfejsu API aprowizacji, zgodnie z wcześniejszym opisem.
- Zobacz Przypisywanie ról aplikacji do aplikacji.
- Interfejs API, dla którego musisz przypisać uprawnienia, to AzureCommunicationsGateway, wymieniony w obszarze Interfejsy API używane przez moją organizację.
Jako administrator dzierżawy zezwól aplikacji na używanie przypisanych ról aplikacji. Zobacz Udzielanie zgody administratora.

Interfejs API aprowizacji używa standardowych łańcuchów zaufania firmy Microsoft dla certyfikatów zabezpieczeń.

Kluczowe pojęcia

Platforma aprowizacji bramy usługi Azure Communications Gateway umożliwia aprowizowanie numerów do użycia z usługami, takimi jak Routing bezpośredni w usłudze Microsoft Teams lub Exchange dostawcy zoom. Platforma aprowizacji ma dwa kluczowe zasoby, które można kontrolować: konta i liczby.

Zasoby konta to opisy klientów (zazwyczaj przedsiębiorstwa) i ustawienia poszczególnych klientów na potrzeby aprowizacji usług.
Liczba zasobów należy do konta. Opisują one numery telefonów (TN), usługi używane przez numery (na przykład routing bezpośredni w usłudze Microsoft Teams) oraz wszelkie dodatkowe konfiguracje liczby.

Aby na przykład udostępnić klientowi usługę routingu bezpośredniego w usłudze Microsoft Teams, contoso, utwórz zasób konta za pomocą interfejsu API aprowizacji dla firmy Contoso. Konto zawiera konfigurację routingu bezpośredniego (na przykład poddomeny i odpowiednie tokeny wymagane do skonfigurowania rekordów DNS, których usługa Microsoft Teams może użyć do zweryfikowania konfiguracji klienta). Następnie musisz dodać zasoby liczbowe do konta i włączyć każdą liczbę dla routingu bezpośredniego. Komunikacja równorzędna w chmurze zoom phone wymaga również zasobów konta i liczby, ale konta Zoom nie zawierają tej samej konfiguracji dla poddomeny i odpowiednich tokenów.

Ważne

Musisz włączyć usługę zarówno na koncie, jak i na numerach w ramach konta.

Przykłady

W poniższych przykładach przedstawiono przykładowe żądania tworzenia kont i numerów oraz zarządzania nimi.

Tworzenie konta do reprezentowania klienta

Użyj funkcji PUT w punkcie końcowym, accounts/<accountName> aby utworzyć konto o nazwie contoso dla klienta Contoso i skonfigurować co najmniej jedną usługę komunikacji dla konta. Użyj nagłówka If-None-Match, aby sprawdzić, czy zasób konta o tej nazwie jeszcze nie istnieje.

W poniższym przykładzie:

Routing bezpośredni jest skonfigurowany.
Osłona identyfikatora obiektu wywołującego jest włączona (wartość domyślna).
Poddomena klienta to contoso.
Podane przez klienta wartości TXT DNS potrzebne do skonfigurowania rekordów DNS znajdują się w region1Token polach i region2Token .

Żądanie:

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

Odpowiedź:

HTTP/1.1 201 Created

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

Wyświetlanie szczegółów konta

Użyj polecenia GET w accounts/<accountName> punkcie końcowym, aby uzyskać szczegółowe informacje o koncie i sprawdzić, czy konfigurowanie rekordów DNS dla skonfigurowanej poddomeny zakończyło się pomyślnie (tylko wymagane dla routingu bezpośredniego w usłudze Microsoft Teams). Odpowiedź zawiera następujące pola:

directRoutingProvisioningState, reprezentując stan rekordów DNS. To pole jest uwzględniane, gdy parametr ?status=true zapytania jest określony w żądaniu i ma zastosowanie tylko w przypadku routingu bezpośredniego.
Wszystkie konfiguracje zostały wcześniej ustawione (lub domyślne, jeśli pole nie zostało ustawione).
Element ETag reprezentujący bieżący stan konta. Możesz użyć wartości w nagłówku If-Match kolejnych żądań aktualizacji, aby upewnić się, że nie zastąpisz zmian wprowadzonych przez innych użytkowników interfejsu API.

Żądanie:

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

Odpowiedź:

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

Aktualizowanie konfiguracji konta

Użyj funkcji PUT w punkcie accounts/<accountName> końcowym, aby zaktualizować konfigurację konta. Aby upewnić się, że aktualizacja nie zastępuje zmiany wprowadzonej przez innego użytkownika, dodaj nagłówek If-Match z tagu ETag z najnowszej odpowiedzi dla konta.

Żądanie:

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

Odpowiedź:

HTTP/1.1 200 OK

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

Dodawanie jednego numeru do konta

Użyj funkcji PUT w punkcie account/<accountName>/numbers/<phoneNumber> końcowym, aby dodać numer E.164 do konta, włączyć co najmniej jedną usługę komunikacji i dodać dodatkową konfigurację. Wybrane usługi komunikacyjne muszą być również skonfigurowane na koncie. Użyj nagłówka If-None-Match, aby sprawdzić, czy zasób liczbowy z tą liczbą jeszcze nie istnieje.

W poniższym przykładzie:

Liczba to +123451.
Routing bezpośredni jest włączony.
customSipHeader określa, że usługa Azure Communications Gateway powinna dodać nagłówek z wartością exampleHeaderContents do komunikatów wysyłanych do sieci.

Ważne

Nazwa nagłówka niestandardowego jest ustawiana w konfiguracji Azure Portal dla interfejsu API aprowizacji. Jest taka sama dla wszystkich komunikatów.

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

Odpowiedź:

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

Aktualizowanie konfiguracji dla liczby

Użyj funkcji PUT w punkcie końcowym, account/<accountName>/numbers/<phoneNumber> aby zaktualizować konfigurację dla liczby. Aby upewnić się, że aktualizacja nie zastępuje zmiany wprowadzonej przez innego użytkownika, dodaj nagłówek If-Match z tagu ETag z najnowszej odpowiedzi dla liczby.

Żądanie:

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

Odpowiedź:

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

Dodawanie lub aktualizowanie wielu liczb jednocześnie

Użyj funkcji POST w punkcie account/<accountName>/numbers:batch końcowym, aby jednocześnie dodać do konta maksymalnie 100 liczb. Ten punkt końcowy może służyć również do aktualizowania numerów na koncie. Liczby są dodawane transakcyjnie: w przypadku niepowodzenia aktualizacji wszystkie aktualizacje kończą się niepowodzeniem.

Żądanie:

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

Odpowiedź:

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

Pobieranie wszystkich liczb na koncie

Użyj polecenia GET w punkcie account/<accountName>/numbers końcowym, aby pobrać wszystkie liczby na koncie z ich konfiguracją. skip Użyj parametrów zapytania i maxpagesize , aby kontrolować sposób dzielenia odpowiedzi na strony. Jeśli zostanie zwróconych więcej liczb, odpowiedź będzie zawierać nextLink pole wskazujące adres URL żądania uzyskania następnej strony wyników.

Żądanie:

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

Odpowiedź:

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

Rozwiązywanie problemów

Usługa Teams Direct Routing nie działa w przypadku liczb na koncie.
- Sprawdź, czy token DNS został zweryfikowany, wysyłając polecenie GET na koncie z parametrem ?status=true zapytania i sprawdź, czy parametr directRoutingProvisioningState ma subdomainStatus wartość .Provisioned
Skonfigurowano liczbę do korzystania z routingu bezpośredniego/powiększania, ale wydaje się, że nie działa.
- Sprawdź, czy konto jest skonfigurowane do używania routingu bezpośredniego/powiększenia i czy liczba ma włączoną tę konkretną funkcję.
Mogę skontaktować się z interfejsem API, ale po wykonaniu wielu żądań moje połączenia zaczynają przekraczać limit czasu.
- Interfejs API aprowizacji jest ograniczony. Aby uzyskać szczegółowe informacje , zobacz Limity, limity przydziału i ograniczenia usługi Azure Communications Gateway . Zwolnij miejsce na żądania lub użyj punktu końcowego wsadowego, aby uniknąć ograniczenia szybkości. Limit szybkości zostanie przekroczony w końcu i będzie można nawiązać połączenie.

Następne kroki

Rozpocznij integrację z interfejsem API aprowizacji usługi Azure Communications Gateway.

Interfejs API aprowizacji usługi Azure Communications Gateway

Wprowadzenie

Wymagania wstępne

Uwierzytelnianie i autoryzacja

Kluczowe pojęcia

Przykłady

Tworzenie konta do reprezentowania klienta

Wyświetlanie szczegółów konta

Aktualizowanie konfiguracji konta

Dodawanie jednego numeru do konta

Aktualizowanie konfiguracji dla liczby

Dodawanie lub aktualizowanie wielu liczb jednocześnie

Pobieranie wszystkich liczb na koncie

Rozwiązywanie problemów

Następne kroki

Dodatkowe zasoby