Interfejs API aprowizacji usługi Azure Communications Gateway

Interfejs API aprowizacji usługi Azure Communications Gateway dla operatorów telekomunikacyjnych umożliwia aprowizowanie szczegółów klientów i przypisanych im numerów do usługi Azure Communications Gateway (ACG). Interfejs API aprowizacji obsługuje również aprowizację przepływową niektórych usług komunikacji zaplecza.

Aprowizowanie klientów i numerów jest obowiązkowe (przy użyciu interfejsu API aprowizacji lub portalu zarządzania numerami w przeglądarce) dla wszystkich przypadków użycia, z wyjątkiem opcji Operator Connect i Telefon w Teams Mobile. W przypadku opcji Operator Connect i Telefon w Teams Mobile użycie interfejsu API aprowizacji i/lub portalu zarządzania numerami jest opcjonalne i można je zintegrować bezpośrednio z interfejsem API Łączenia operatorów.

Wprowadzenie

Wymagania wstępne

• Dzierżawa z wdrożona aplikacją usługi Azure Communications Gateway.
• W pełni kwalifikowana nazwa domeny (FQDN) dla bramy usługi Azure Communications Gateway wyświetlana na stronie Przegląd zasobu w Azure Portal. Interfejs API jest dostępny na porcie 443 z provapi.<base-domain>.
• 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. Aby uzyskać dostęp do interfejsu API aprowizacji, aplikacja kliencka musi uzyskać prawidłowy token elementu nośnego uwierzytelniania. Token elementu nośnego wskazuje, że aplikacja jest autoryzowana dla co najmniej jednego zakresu (ról) dla interfejsu API aprowizacji. Zalecamy używanie przepływu poświadczeń klienta (przeznaczonego do przetwarzania po stronie serwera).

Następujące zakresy są dostępne dla interfejsu API aprowizacji:

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

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

1. 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ć https://func-voiceservice-rp-prod-eastuseuap.azurewebsites.net/.defaultwartość .
     client_id	wymagane	Identyfikator aplikacji (klienta) przypisany do aplikacji.

   • Oświadczenie roles w odebrany token określa role (zakresy), do których aplikacja kliencka ma autoryzację 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życia tokenów.

2. 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.
3. Przypisz siebie jako właściciela do rejestracji aplikacji. Zobacz Przypisywanie właściciela aplikacji.
4. 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ę.
5. 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 ma trzy kluczowe zasoby, którymi operator może zarządzać: kontami, liczbami i żądaniami uzyskania informacji.

• Zasoby konta to opisy klientów operatorów (zazwyczaj, przedsiębiorstwa) i ustawień poszczególnych klientów na potrzeby aprowizacji usług.
• Liczba zasobów należy do konta. Opisują one liczby, usługi (na przykład routing bezpośredni w usłudze Microsoft Teams), z których korzystają liczby, oraz wszelkie dodatkowe konfiguracje na liczbę.
• Żądania zasobów informacji (RFI) to opisy potencjalnych klientów dla operatorów, którzy wyrażają zainteresowanie odbieraniem usług od operatora za pośrednictwem określonych usług zaplecza. Obecnie dostępne są tylko rfi utworzone z programu Operator Connect i Telefon w Teams zgody na urządzenia przenośne.

Aby na przykład udostępnić klientowi usługę Routing bezpośredni w usłudze Microsoft Teams, contoso, utwórz zasób konta przy użyciu 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 należy dodać zasoby liczbowe do konta i włączyć każdą liczbę dla routingu bezpośredniego.

Porada

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

Aprowizowanie usług zaplecza za pomocą synchronizacji usługi zaplecza

Usługa Azure Communications Gateway musi zawierać informacje o numerach, do których świadczy usługę w celu prawidłowego łączenia połączeń. Zalecamy, aby interfejs API aprowizacji usługi Azure Communications Gateway dostarczał te informacje do usługi Azure Communications Gateway, ale można również użyć portalu zarządzania numerami. Większość usług zaplecza musi być również aprowizowana przy użyciu informacji o liczbach i kontach, które mają być używane. To wymaganie często oznacza, że do włączenia nowych usług jest potrzebnych wiele projektów integracji IT. Platforma aprowizacji usługi Azure Communications Gateway została wstępnie wstępnie utworzona z niektórymi usługami zaplecza, aby aprowizować je dla Ciebie, zmniejszając wymagania dotyczące integracji IT. Tej funkcji można użyć, włączając synchronizację usługi zaplecza dla odpowiednich usług. Oznacza to również, że każda integracja IT z platformą aprowizacji usługi Azure Communications Gateway jest wielokrotnego użytku w przypadku innych usług zaplecza.

Na przykład Operator Connect nakazuje przekazywanie wszystkich liczb za pośrednictwem interfejsu API Łączenia operatorów. Jeśli synchronizacja usługi zaplecza jest włączona dla programu Operator Connect, dowolna liczba aprowizowana w usłudze Azure Communications Gateway i włączona dla programu Operator Connect zostanie automatycznie aprowizowana w programie Operator Connect, co oznacza, że nie trzeba integrować się z interfejsem API łączenia operatora.

Aprowizowanie za pośrednictwem platformy aprowizacji usługi Azure Communications Gateway jest opcjonalne w przypadku niektórych usług, w których usługa Azure Communications Gateway może uzyskać informacje bezpośrednio z zaplecza. Jednak niektóre funkcje, takie jak dodanie nagłówków SIP klienta do celów rozliczeniowych, nie będą dostępne. W przypadku wszystkich usług, które nie obsługują synchronizacji usługi zaplecza, może być wymagana inna integracja IT bezpośrednio z usługą zaplecza. Stan obsługi aprowizacji opisano w poniższej tabeli:

Usługa zaplecza	Wymaganie aprowizacji za pośrednictwem platformy aprowizacji ACG	Obsługiwana aprowizacja usługi zaplecza
Routing bezpośredni	Obowiązkowy	❌
Zoom	Obowiązkowy	❌
Ochrona połączeń operatora platformy Azure	Obowiązkowy	❌
Operator Connect	Opcjonalne	✅
Telefon w Teams Mobile	Opcjonalne	✅

Synchronizacja z usługami zaplecza jest asynchroniczna, co oznacza, że żądanie aprowizacji może zakończyć się powodzeniem przed aprowizowaniem usługi zaplecza. Ten stan jest oznaczany w odpowiedzi interfejsu API przy użyciu pola ustawionego serviceProvisioningStatus na wartość pending. Zalecamy wykonanie zapytania względem obiektu w celu sprawdzenia stanu aprowizacji do momentu ustawienia tego pola na successwartość . Wszelkie błędy związane z aprowizowaniem systemu zaplecza są udostępniane bezpośrednio w odpowiedzi.

Przykłady

W poniższych przykładach pokazano przykładowe żądania zarządzania RFI, kontami i liczbami.

Twórca konto reprezentujące klienta

Użyj polecenia PUT w punkcie accounts/<accountName> końcowym, 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=2024-02-29 HTTP/1.1
{
  "name": "contoso",
  "serviceDetails": {
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1TokenValue",
          "region2Token": "region2TokenValue"
        }
      }
    }
  }
}

Odpowiedź:

{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1TokenValue",
          "region2Token": "region2TokenValue"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

W poniższym przykładzie utworzymy konto do użycia tylko z programem Teams Operator Connect z włączoną synchronizacją zaplecza, aby informacje o tym koncie (takie jak wszystkie przekazane liczby) były również aprowizowane w usłudze Teams:

Żądanie:

PUT /accounts/contoso?api-version=2024-02-29 HTTP/1.1
{
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true
    },
  }
}

Odpowiedź:

{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0
    }
  }
}

Wyświetlanie szczegółów konta

Użyj polecenia GET w punkcie końcowym, accounts/<accountName> aby uzyskać szczegółowe informacje o koncie. Odpowiedź zawiera następujące pola:

• Wszystkie konfiguracje zostały wcześniej ustawione (lub domyślne, jeśli pole nie zostało ustawione).
• Liczba subskrybentów dla każdej z usług dostępnych w usłudze ACG.
• Stan aprowizacji usługi zaplecza, jeśli jest włączony.
• subdomainStatus, reprezentując stan aprowizacji rekordów DNS, dotyczy tylko routingu bezpośredniego.
• Nagłówek 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=2024-02-29 HTTP/1.1

Odpowiedź:

ETag: 12345
{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0
    },
  }
}

Równoważne żądanie, jeśli konto ma skonfigurowaną wiele usług, pojawia się w następujący sposób:

Żądanie:

GET /accounts/contoso?api-version=2024-02-29 HTTP/1.1

Odpowiedź:

ETag: 12345
{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": true,
      "enabled": true
    },
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1",
          "region2Token": "region2"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

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 If-Match nagłówek z tagiem ETag z najnowszej odpowiedzi dla konta.

Żądanie:

PUT /accounts/contoso?api-version=2024-02-29 HTTP/1.1
ETag: 12345
{
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": false,
      "enabled": true
    },
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1",
          "region2Token": "region2"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

Odpowiedź:

ETag: 56789
{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "name": "contoso",
  "serviceDetails": {
    "teamsTenantId": "tenantIdString",
    "teamsOperatorConnect": {
      "syncEnabled": false,
      "enabled": true
    },
    "teamsDirectRouting": {
      "syncEnabled": true,
      "enabled": true,
      "numberCount": 0,
      "configuration": {
        "callScreening": true,
        "subdomain": "contoso",
        "subdomainTokens": {
          "region1Token": "region1",
          "region2Token": "region2"
        }
      },
      "subdomainStatus": "provisioned"
    },
  }
}

Dodawanie jednego numeru do konta

Użyj funkcji PUT w punkcie account/<accountName>/numbers/<telephoneNumber> końcowym, aby dodać liczbę do konta, włączyć co najmniej jedną usługę komunikacji i dodać dowolną inną 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. Wszystkie liczby muszą zostać utworzone w formacie E.164.

W poniższym przykładzie:

• Liczba to +123451.
• Połączenie operatorów jest włączone.
• Podano konfigurację wymaganą do przekazania numeru do programu Operator Connect
• customSipHeader określa, że usługa Azure Communications Gateway powinna dodać nagłówek z wartością exampleHeaderContents do komunikatów wysyłanych do sieci operatora. Nazwa nagłówka jest ustawiana w ramach wdrażania usługi Azure Communications Gateway.
• Pole serviceProvisioningStatus w odpowiedzi pokazuje stan synchronizacji z usługą zaplecza.

PUT /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1
{
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Odpowiedź:

{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Sprawdzanie stanu aprowizacji po pewnym czasie

Użyj polecenia GET po account/<accountName>/numbers/<telephoneNumber> akcji aprowizacji, aby sprawdzić stan liczby. Jeśli liczba została pomyślnie aprowizowana, serviceProvisioningStatus pole zostanie zaktualizowane z pending do synced.

Żądanie:

GET /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1

Odpowiedź:

{
  "serviceProvisioningStatus": "synced",
  "serviceProvisioningErrors": null,
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Błąd podczas aprowizacji usługi zaplecza na potrzeby przekazywania numeru

W tym przykładzie aprowizowanie zaplecza podczas przekazywania numeru powoduje wystąpienie błędu, który jest odzwierciedlany z powrotem w odpowiedzi. Komunikaty o błędach są przekazywane w sposób niewidoczny dla usług zaplecza.

Uwaga

Początkowo podczas aprowizacji numeru ma pending stan, który musi zostać ponownie zapytany, aby potwierdzić powodzenie/niepowodzenie.

Oryginalne żądanie, które nie ma wartości pola usage :

PUT /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1
{
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "configuration": {
        "usage": "",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Odpowiedź z zapytania GET po pewnym czasie:

{  
  "serviceProvisioningStatus": "failed",
  "serviceProvisioningErrors": [
    {
      "code": "InvalidRequest",
      "message": "Invalid/missing required configuration attributes: Usage",
      "target": "oc",
    }
  ],
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }

Aktualizowanie konfiguracji dla liczby

Użyj funkcji PUT w punkcie account/<accountName>/numbers/<telephoneNumber> końcowym, 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 numeru.

Żądanie:

PUT /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1
ETag: 123
{
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling",
          "Mobile"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Odpowiedź:

{
  "serviceProvisioningStatus": "pending",
  "serviceProvisioningErrors": null,
  "telephoneNumber": "+123451",
  "accountName": "contoso",
  "serviceDetails": {
    "teamsOperatorConnect": {
      "enabled": true,
      "assignmentStatus": "assigned",
      "configuration": {
        "usage": "CallingUserAssignment",
        "choosableCapabilities": [
          "InboundCalling",
          "OutboundCalling",
          "Mobile"
        ],
        "civicAddressId": "civicAddressIdString",
        "allowTenantAddressUpdate": true,
      }
    },
  },
  "configuration": {
    "customSipHeader": "exampleHeaderContents"
  }
}

Wyświetlanie listy żądań informacji

Użyj polecenia GET w /teamsRequestsForInformation punkcie końcowym, aby uzyskać listę zgody usługi Teams, które zostały przesłane przez potencjalnych klientów.

Żądanie:

GET /teamsRequestsForInformation?api-version=2024-02-29 HTTP/1.1

Odpowiedź:

{
  "value": [
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "id": "contoso",
      "tenantId": "contosoTenantId",
      "accountName": "contoso",
      "productContext": "teams",
      "operatorId": "string",
      "status": "active",
      "consentedOn": "2024-05-07T11:15:10.519Z",
      "lastModifiedOn": "2024-05-07T11:15:10.519Z",
      "consentedCountries": [
        "string"
      ],
      "contacts": [
        {
          "fullName": "Example Name",
          "email": "example@contoso.com",
          "telephoneNumber": "+1234567890",
          "companyName": "contoso",
          "companySize": "size"
        }
      ],
      "customerRelationship": {
        "status": "example status",
        "lastModifiedOn": "2024-05-07T11:15:10.520Z",
        "comment": "example comment"
      }
    },
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "id": "contoso2",
      "tenantId": "contosoTenantId2",
      "accountName": "contoso2",
      "productContext": "teams",
      "operatorId": "string",
      "status": "active",
      "consentedOn": "2024-05-07T11:15:10.519Z",
      "lastModifiedOn": "2024-05-07T11:15:10.519Z",
      "consentedCountries": [
        "string"
      ],
      "contacts": [
        {
          "fullName": "Example Name2",
          "email": "example@contoso2.com",
          "telephoneNumber": "+1234567891",
          "companyName": "contoso2",
          "companySize": "size"
        }
      ],
      "customerRelationship": {
        "status": "example status",
        "lastModifiedOn": "2024-05-07T11:15:10.520Z",
        "comment": "example comment"
      }
    },
    ... // more RFIs
  ],
  "nextLink": "string"
}

Aktualizowanie żądania informacji

Użyj funkcji PATCH w /teamsRequestsForInformation/<tenantID> punkcie końcowym, aby zaktualizować stan interfejsu RFI, który jest odzwierciedlony w usłudze zaplecza. Operator Connect i Telefon w Teams Mobile umożliwia wskazanie stanu żądania z powrotem do klienta końcowego, dzięki czemu zaktualizowany stan jest wyświetlany w Centrum Administracja Teams klienta.

Żądanie

PATCH /teamsRequestsForInformation/contosoTenantId
{
  "customerRelationship": {
    "status": "new status",
    "comment": "new comment"
  }
}

Reakcja

{
    {
      "serviceProvisioningStatus": "pending",
      "serviceProvisioningErrors": null,
      "id": "contoso",
      "tenantId": "contosoTenantId",
      "accountName": "contoso",
      "productContext": "teams",
      "operatorId": "string",
      "status": "active",
      "consentedOn": "2024-05-07T11:15:10.519Z",
      "lastModifiedOn": "2024-05-07T11:15:10.519Z",
      "consentedCountries": [
        "string"
      ],
      "contacts": [
        {
          "fullName": "Example Name",
          "email": "example@contoso.com",
          "telephoneNumber": "+1234567890",
          "companyName": "contoso",
          "companySize": "size"
        }
      ],
      "customerRelationship": {
        "status": "new status",
        "lastModifiedOn": "2024-05-07T12:15:10.520Z",
        "comment": "new comment"
      }
    }
}

Wyświetlanie listy wszystkich numerów przypisanych do konta

Użyj żądania GET w /accounts/<accountName>/numbers punkcie końcowym, aby uzyskać listę numerów, które zostały zaaprowizowane dla tego konta.

Żądanie:

GET /accounts/contoso/numbers?api-version=2024-02-29 HTTP/1.1

Odpowiedź dla konta z tylko numerami Połączenia operatorów:

{
  "value": [
    {
      "serviceProvisioningStatus": "pending",
      "serviceProvisioningErrors": null,
      "telephoneNumber": "+123451",
      "accountName": "contoso",
      "serviceDetails": {
        "teamsOperatorConnect": {
          "enabled": true,
          "assignmentStatus": "assigned",
          "configuration": {
            "usage": "CallingUserAssignment",
            "choosableCapabilities": [
              "InboundCalling",
              "OutboundCalling",
              "Mobile"
            ],
            "civicAddressId": "civicAddressIdString",
            "allowTenantAddressUpdate": true,
          }
        },
      },
      "configuration": {
        "customSipHeader": "exampleHeaderContents"
      }
    },
    ... // more OC numbers
  ],
  nextLink: "string"
}

Odpowiedź na konto z aprowizowaną liczbą połączeń operatorów i routingu bezpośredniego:

{
  "value": [
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "telephoneNumber": "+123451",
      "accountName": "contoso",
      "serviceDetails": {
        "teamsOperatorConnect": {
          "enabled": true,
          "assignmentStatus": "assigned",
          "configuration": {
            "usage": "CallingUserAssignment",
            "choosableCapabilities": [
              "InboundCalling",
              "OutboundCalling",
              "Mobile"
            ],
            "civicAddressId": "civicAddressIdString",
            "allowTenantAddressUpdate": true,
          }
        },
      },
      "configuration": {
        "customSipHeader": "exampleHeaderContents"
      }
    },
    {
      "serviceProvisioningStatus": "synced",
      "serviceProvisioningErrors": null,
      "telephoneNumber": "+123452",
      "accountName": "contoso",
      "serviceDetails": {
        "teamsDirectRouting": {
          "enabled": true
        }
      },
      "configuration": {
        "customSipHeader": "exampleHeaderContents"
      }
    },
    ... // more DR and OC numbers
  ],
  nextLink: "string"
}

Wyświetlanie listy wszystkich lokalizacji awaryjnych dla określonego konta

Użyj żądania GET w /accounts/<accountName>/teamsCivicAddresses punkcie końcowym, aby uzyskać pełną listę adresów obywatelskich skonfigurowanych w usłudze Teams Administracja Center dla tego konta. Możesz użyć populacji tej listy jako locationid podczas tworzenia lub aktualizowania liczb w ramach konta.

Żądanie:

GET /accounts/contoso/teamsCivicAddresses?api-version=2024-02-29 HTTP/1.1

Odpowiedź:

{
  "value": [
    {
      "id": "string",
      "country": "string",
      "houseNumber": "string",
      "houseNumberSuffix": "string",
      "preDirectional": "string",
      "streetName": "string",
      "streetSuffix": "string",
      "postDirectional": "string",
      "stateOrProvince": "string",
      "countyOrDistrict": "string",
      "cityOrTown": "string",
      "cityOrTownAlias": "string",
      "postalOrZipCode": "string",
      "description": "string",
      "companyName": "string",
      "companyId": "string",
      "defaultLocationId": "string",
      "validationStatus": "notValidated",
      "tenantId": "string",
      "partnerId": "string",
      "locations": [
        {
          "id": "string",
          "civicAddressId": "string",
          "description": "string",
          "additionalInfo": "string",
          "isDefault": true,
          "elin": "string"
        }
      ],
      "latitude": "string",
      "longitude": "string"
    },
    ... // more locations
  ],
  "nextLink": "string"
}

Usuwanie numeru z konta

Użyj polecenia DELETE w punkcie /accounts/<accountName>/numbers/<telephoneNumber> końcowym, aby zwolnić numer z dzierżawy. Ta operacja spowoduje anulowanie przypisania numeru od użytkownika, jeśli zostanie przypisany, a następnie zwolni numer z dzierżawy.

Żądanie:

DELETE /accounts/contoso/numbers/+123451?api-version=2024-02-29 HTTP/1.1

Odpowiedź:

204 Status Code

Rozwiązywanie problemów

• Routing bezpośredni w usłudze Teams nie działa dla numerów na koncie.

  • Sprawdź, czy token DNS został zweryfikowany, wysyłając polecenie GET na koncie, sprawdzając, czy serviceDetails.teamsDirectRouting ma subdomainStatus wartość równą Provisioned.

• Skonfigurowano liczbę do używania routingu bezpośredniego/powiększenia, ale wydaje się, że nie działa.

  • Sprawdź, czy konto zostało skonfigurowane do używania routingu bezpośredniego/powiększenia i czy numer ma włączoną tę konkretną funkcję.

• Udało mi się skontaktować z interfejsem API, ale po wykonaniu wielu żądań moje połączenia zaczynają przekraczać limit czasu.

  • Interfejs API aprowizacji jest ograniczony (do rozsądnej liczby sekund). Zwolnij liczbę żądań 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

Zacznij integrować się z interfejsem API aprowizacji usługi Azure Communications Gateway.