Criar canal

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Crie um novo canal em uma equipe, conforme especificado no corpo da solicitação. Quando você cria um canal, o comprimento máximo do canal displayName é de 50 caracteres. Esse nome de exibição aparece para o usuário no Microsoft Teams.

Você pode adicionar no máximo 200 membros ao criar um canal privado.

Observação

  • Alguns caracteres especiais no nome do canal fazem com que a API Get filesFolder retorne um erro. Para mais detalhes, confira Problemas conhecidos.
  • Quando você cria um canal privado ou compartilhado, o site do SharePoint pode falhar ao provisionar. Se o site não for provisionado após cinco minutos, use a API Get filesFolder para disparar o provisionamento.
  • Inicialmente, você pode criar canais compartilhados com apenas um proprietário. Adicionar vários proprietários resulta em um código de 400 Bad Request erro. Após a solicitação inicial, você pode adicionar mais proprietários usando a API Adicionar membro ao canal .
  • Não há suporte para a criação de canal compartilhado no Microsoft Graph China (21Vianet).

Essa API está disponível nas seguintes implantações de nuvem nacional.

Serviço global Governo dos EUA L4 US Government L5 (DOD) China operada pela 21Vianet
✅ ✅ ✅ ✅

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Essa API dá suporte a permissões de administrador. Os administradores de serviços do Microsoft Teams podem acessar equipes das quais não são membros.

Tipo de permissão Permissões menos privilegiadas Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante) Channel.Create Directory.ReadWrite.All, Group.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application Channel.Create.Group Channel.Create, Directory.ReadWrite.All, Group.ReadWrite.All, Teamwork.Migrate.All

Observação

  • A permissão Channel.Create.Group usa o consentimento específico do recurso.
  • As permissões Group.ReadWrite.All e Directory.ReadWrite.All têm suporte apenas para compatibilidade com versões anteriores. Recomendamos que você atualize suas soluções para usar uma permissão alternativa listada na tabela anterior e evite usar essas permissões daqui para frente.

Observação: no futuro, a Microsoft poderá exigir que você ou seus clientes paguem taxas adicionais com base na quantidade de dados importados usando Teamwork.Migrate.All e/ou APIs de migração.

Solicitação HTTP

POST /teams/{team-id}/channels

Cabeçalhos de solicitação

Cabeçalho Valor
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/json. Obrigatório.

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON de um objeto de canal .

Resposta

Se for bem-sucedido, esse método retornará um 201 Created código de resposta e um objeto de canal no corpo da resposta para um canal com um valor membershipType de standard ou private. Para um canal com um valor membershipType de , esse método retorna um 202 Accepted código de sharedresposta e um link para o teamsAsyncOperation.

Se a solicitação não for bem-sucedida, este método retorna um código de resposta 400 Bad Request. Os seguintes são motivos comuns para esta resposta:

  • createdDateTime é definido no futuro.
  • createdDateTime está corretamente especificado, mas o atributo de instância channelCreationMode está ausente ou definido como um valor inválido.

Exemplos

Exemplo 1: Criar um canal padrão

Solicitação

O exemplo a seguir mostra uma solicitação para criar um canal padrão.

POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels
Content-type: application/json

{
  "displayName": "Architecture Discussion",
  "description": "This channel is where we debate all future architecture plans",
  "membershipType": "standard"
}

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2",
  "displayName": "Architecture Discussion",
  "description": "This channel is where we debate all future architecture plans"
}

Exemplo 2: Criar canal privado em nome do usuário

Solicitação

O exemplo a seguir mostra uma solicitação para criar um canal privado e adicionar um usuário como proprietário da equipe.

POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels
Content-type: application/json

{
  "@odata.type": "#Microsoft.Graph.channel",
  "membershipType": "private",
  "displayName": "My First Private Channel",
  "description": "This is my first private channels",
  "members":
     [
        {
           "@odata.type":"#microsoft.graph.aadUserConversationMember",
           "user@odata.bind":"https://graph.microsoft.com/beta/users('62855810-484b-4823-9e01-60667f8b12ae')",
           "roles":["owner"]
        }
     ]
}

Observação: Para adicionar uma conta de convidado ao canal, para a propriedade roles , use o valor guest.

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('57fb72d0-d811-46f4-8947-305e6072eaa5')/channels/$entity",
    "id": "19:33b76eea88574bd1969dca37e2b7a819@thread.skype",
    "displayName": "My First Private Channel",
    "description": "This is my first private channels",
    "isFavoriteByDefault": null,
    "email": "",
    "webUrl": "https://teams.microsoft.com/l/channel/19:33b76eea88574bd1969dca37e2b7a819@thread.skype/My%20First%20Private%20Channel?groupId=57fb72d0-d811-46f4-8947-305e6072eaa5&tenantId=0fddfdc5-f319-491f-a514-be1bc1bf9ddc",
    "membershipType": "private"
}

Exemplo 3: Criar um canal com o tipo de layout de chat

O exemplo a seguir mostra como criar um canal com o tipo de layout de chat que fornece uma experiência de threading semelhante a chat semelhante a chats em grupo.

Solicitação

O exemplo a seguir mostra uma solicitação para criar um canal com layoutType definido como chat.

POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels
Content-type: application/json

{
  "displayName": "Project Collaboration",
  "description": "Discussion space for project team collaboration",
  "membershipType": "standard",
  "layoutType": "chat"
}

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('57fb72d0-d811-46f4-8947-305e6072eaa5')/channels/$entity",
  "id": "19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2",
  "createdDateTime": "2024-12-08T12:30:45.123Z",
  "displayName": "Project Collaboration",
  "description": "Discussion space for project team collaboration",
  "membershipType": "standard",
  "layoutType": "chat",
  "isFavoriteByDefault": false,
  "email": "",
  "webUrl": "https://teams.microsoft.com/l/channel/19%3A4b6bed8d24574f6a9e436813cb2617d8%40thread.tacv2/Project%20Collaboration?groupId=57fb72d0-d811-46f4-8947-305e6072eaa5&tenantId=0afeb5d5-a667-4716-8fc7-733024389e91",
  "tenantId": "0afeb5d5-a667-4716-8fc7-733024389e91"
}

Exemplo 4: Criar um canal no modo de migração

Solicitação

O exemplo a seguir mostra como criar um canal para importar mensagens.

POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels
Content-Type: application/json

{
  "@microsoft.graph.channelCreationMode": "migration",
  "displayName": "Import_150958_99z",
  "description": "Import_150958_99z",
  "createdDateTime": "2020-03-14T11:22:17.067Z"
}

Resposta

O exemplo a seguir mostra a resposta. O Content-Location cabeçalho na resposta especifica o caminho para o canal que está sendo provisionado. Depois de provisionado, esse canal pode ser usado para importar mensagens.

HTTP/1.1 201 Created
Location: /teams('57fb72d0-d811-46f4-8947-305e6072eaa5')/channels('19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2')

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('57fb72d0-d811-46f4-8947-305e6072eaa5')/channels/$entity",
    "id": "19:987c7a9fbe6447ccb3ea31bcded5c75c@thread.tacv2",
    "createdDateTime": null,
    "displayName": "Import_150958_99z",
    "description": "Import_150958_99z",
    "isFavoriteByDefault": null,
    "email": null,
    "webUrl": null,
    "membershipType": null,
    "moderationSettings": null
}

Exemplo 5: Criar canal padrão com configurações de moderação

Solicitação

O exemplo a seguir mostra uma solicitação para criar um canal padrão com configurações de moderação. Esta operação só pode ser realizada para um canal padrão.

POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels
Content-type: application/json

{
    "displayName": "TestChannelModeration",
    "description": "Test channel moderation.",
    "membershipType": "standard",
    "moderationSettings": {
        "userNewMessageRestriction": "everyoneExceptGuests",
        "replyRestriction": "everyone",
        "allowNewMessageFromBots": true,
        "allowNewMessageFromConnectors": true
    }
}

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('57fb72d0-d811-46f4-8947-305e6072eaa5')/channels/$entity",
    "id": "19:12b76eea88574bd1969dca37e2b7a819@thread.skype",
    "displayName": "My First Private Channel",
    "description": "This is my first private channels",
    "isFavoriteByDefault": null,
    "email": "",
    "webUrl": "https://teams.microsoft.com/l/channel/19:12b76eea88574bd1969dca37e2b7a819@thread.skype/My%20First%20Private%20Channel?groupId=57fb72d0-d811-46f4-8947-305e6072eaa5&tenantId=0fddfdc5-f319-491f-a514-be1bc1bf9ddc",
    "membershipType": "standard"
}

Exemplo 6: Criar um canal privado em nome do usuário usando o nome UPN

Solicitação

O exemplo a seguir mostra uma solicitação para criar um canal privado e adicionar um usuário como proprietário da equipe.

POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels
Content-type: application/json

{
  "@odata.type": "#Microsoft.Graph.channel",
  "membershipType": "private",
  "displayName": "My First Private Channel",
  "description": "This is my first private channels",
  "members":
     [
        {
           "@odata.type":"#microsoft.graph.aadUserConversationMember",
           "user@odata.bind":"https://graph.microsoft.com/beta/users('jacob@contoso.com')",
           "roles":["owner"]
        }
     ]
}

Observação: Para adicionar uma conta de convidado ao canal, para a propriedade roles , use o valor guest.

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 0

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('57fb72d0-d811-46f4-8947-305e6072eaa5')/channels/$entity",
    "id": "19:33b76eea88574bd1969dca37e2b7a819@thread.skype",
    "displayName": "My First Private Channel",
    "description": "This is my first private channels",
    "isFavoriteByDefault": null,
    "email": "",
    "webUrl": "https://teams.microsoft.com/l/channel/19:33b76eea88574bd1969dca37e2b7a819@thread.skype/My%20First%20Private%20Channel?groupId=57fb72d0-d811-46f4-8947-305e6072eaa5&tenantId=0fddfdc5-f319-491f-a514-be1bc1bf9ddc",
    "membershipType": "private"
}

Exemplo 7: Criar um canal compartilhado em nome de um usuário

Solicitação

O exemplo a seguir mostra como criar um canal compartilhado.

POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels
Content-type: application/json

{
  "displayName": "My First Shared Channel",
  "description": "This is my first shared channel",
  "membershipType": "shared",
  "members": [
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "user@odata.bind": "https://graph.microsoft.com/beta/users('7640023f-fe43-gv3f-9gg4-84a9efe4acd6')",
      "roles": [
        "owner"
      ]
    }
  ]
}

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Location: /teams/7640023f-fe43-4cc7-9bd3-84a9efe4acd6/operations/359d75f6-2bb8-4785-ab2d-377bf3d573fa
Content-Length: 0

Exemplo 8: Criar um canal compartilhado compartilhado com a equipe de host

Solicitação

O exemplo a seguir mostra como criar um canal compartilhado compartilhado com a equipe anfitriã.

POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels
Content-type: application/json

{
  "displayName": "My First Shared Channel",
  "description": "This is my first shared channel",
  "membershipType": "shared",
  "members": [
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "user@odata.bind": "https://graph.microsoft.com/beta/users('7640023f-fe43-gv3f-9gg4-84a9efe4acd6')",
      "roles": [
        "owner"
      ]
    }
  ],
  "sharedWithTeams":[
    {
      "id": "57fb72d0-d811-46f4-8947-305e6072eaa5"
    }
  ]
}

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Location: /teams/7640023f-fe43-4cc7-9bd3-84a9efe4acd6/operations/359d75f6-2bb8-4785-ab2d-377bf3d573fa
Content-Length: 0