Создание расширения сообщений на основе API

  • Статья

Примечание.

Расширения сообщений на основе API поддерживают только команды поиска.

Расширения сообщений на основе API — это возможность приложения Microsoft Teams, которая интегрирует внешние API непосредственно в Teams, повышая удобство использования приложения и обеспечивая простой пользовательский интерфейс. Расширения сообщений на основе API поддерживают команды поиска и могут использоваться для получения и отображения данных из внешних служб в Teams, упрощая рабочие процессы, уменьшая необходимость переключения между приложениями.

Прежде чем приступить к работе, убедитесь, что вы соответствуете следующим требованиям:


1. Описание OpenAPI (OAD)

Убедитесь, что вы придерживаетесь следующих рекомендаций для документа OpenAPI Description (OAD):

  • Поддерживаются версии OpenAPI 2.0 и 3.0.x.
  • Поддерживаемые форматы — JSON и YAML.
  • Текст запроса, если он присутствует, должен иметь значение application/Json.
  • Определите URL-адрес сервера протокола HTTPS для servers.url свойства.
  • Поддерживаются только методы HTTP POST и GET.
  • Документ Описание OpenAPI должен иметь operationId.
  • Допускается только один обязательный параметр без значения по умолчанию.
  • Обязательный параметр со значением по умолчанию считается необязательным.
  • Пользователи не должны вводить параметр для заголовка или файла cookie.
  • Операция не должна иметь обязательный заголовок или параметры файла cookie без значений по умолчанию.
  • Убедитесь, что в документе Описание OpenAPI отсутствуют удаленные ссылки.
  • Создание массивов для запроса не поддерживается; однако вложенные объекты в тексте запроса JSON поддерживаются.
  • Teams не поддерживает oneOfконструкции , anyOf, allOfи not (swagger.io).

Следующий код является примером документа OpenAPI Description:

openapi: 3.0.1
info:
title: OpenTools Plugin
description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
version: 'v1'
servers:
- url: https://gptplugin.opentools.ai
paths:
/tools:
 get:
   operationId: searchTools
   summary: Search for AI Tools
   parameters:
     - in: query
       name: search
       required: true
       schema:
         type: string
       description: Used to search for AI tools by their category based on the keywords. For example, ?search="tool to create music" will give tools that can create music.
   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/searchToolsResponse'
     "400":
       description: Search Error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/searchToolsError'
components:
schemas:
 searchToolsResponse:
   required:
     - search
   type: object
   properties:
     tools:
       type: array
       items:
         type: object
         properties:
           name:
             type: string
             description: The name of the tool.
           opentools_url:
             type: string
             description: The URL to access the tool.
           main_summary:
             type: string
             description: A summary of what the tool is.
           pricing_summary:
             type: string
             description: A summary of the pricing of the tool.
           categories:
             type: array
             items:
               type: string
             description: The categories assigned to the tool.
           platforms:
             type: array
             items:
               type: string
             description: The platforms that this tool is available on.
       description: The list of AI tools.
 searchToolsError:
   type: object
   properties:
     message:
       type: string
       description: Message of the error.

Дополнительные сведения см. в разделе Структура OpenAPI.


2. Манифест приложения

Убедитесь, что вы придерживаетесь следующих рекомендаций для манифеста приложения:

  • Задайте для версии манифеста приложения значение 1.17.

  • Задайте значение composeExtensions.composeExtensionTypeapiBased.

  • Определите composeExtensions.apiSpecificationFile в качестве относительного пути к файлу описания OpenAPI в папке. Это связывает манифест приложения со спецификацией API.

  • Определите apiResponseRenderingTemplateFile в качестве относительного пути к шаблону отрисовки ответа. Это указывает расположение шаблона, используемого для отрисовки ответов API.

  • Каждая команда должна иметь ссылку на шаблон отрисовки ответа. При этом каждая команда подключается к соответствующему формату ответа.

  • Свойство Commands.id в манифесте приложения должно соответствовать свойству в описании operationId OpenAPI.

  • Если обязательный параметр не имеет значения по умолчанию, команда parameters.name в манифесте приложения должна соответствовать в документе parameters.name Описание OpenAPI.

  • Если обязательный параметр отсутствует, команда parameters.name в манифесте приложения должна соответствовать необязательным parameters.name в описании OpenAPI.

  • Убедитесь, что параметры каждой команды точно совпадают с именами параметров, определенных для операции в спецификации OpenAPI.

  • Шаблон отрисовки ответа должен быть определен для каждой команды, которая используется для преобразования ответов из API.

  • Полное описание не должно превышать 128 символов.

    {
"$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
+  "manifestVersion": "devPreview",
"version": "1.0.0",
"id": "04805b4b-xxxx-xxxx-xxxx-4dbc1cac8f89",
"packageName": "com.microsoft.teams.extension",
"developer": {
    "name": "Teams App, Inc.",
    "websiteUrl": "https://www.example.com",
    "privacyUrl": "https://www.example.com/termofuse",
    "termsOfUseUrl": "https://www.example.com/privacy"
},
"icons": {
    "color": "color.png",
    "outline": "outline.png"
},
"name": {
    "short": "AI tools",
    "full": "AI tools"
},
"description": {
    "short": "AI tools",
    "full": "AI tools"
},
"accentColor": "#FFFFFF",
"composeExtensions": [
    {
+      "composeExtensionType": "apiBased",
+      "authorization": {
+        "authType": "apiSecretServiceAuth ",
+        "apiSecretServiceAuthConfiguration": {
+            "apiSecretRegistrationId": "96270b0f-7298-40cc-b333-152f84321813"
+        }
+      },
+      "apiSpecificationFile": "aitools-openapi.yml",
       "commands": [
       {
          "id": "searchTools",
          "type": "query",
          "context": [
             "compose",
             "commandBox"
          ],
          "title": "search for AI tools",
          "description": "search for AI tools",
          "parameters": [
             {
             "name": "search",
             "title": "search query",
             "description": "e.g. search='tool to create music'"
             }
          ],
+          "apiResponseRenderingTemplateFile": "response-template.json"
       }
       ]
    }
],
"validDomains": []
}

Параметры

Имя Описание
composeExtensions.composeExtensionType Тип расширения Compose. Обновите значение на apiBased.
composeExtensions.authorization Сведения об авторизации для расширения сообщений на основе API
composeExtensions.authorization.authType Перечисление возможных типов авторизации. Поддерживаемые значения: none, apiSecretServiceAuthи microsoftEntra.
composeExtensions.authorization.apiSecretServiceAuthConfiguration Объект, фиксирующий сведения, необходимые для проверки подлинности службы. Применимо, только если тип проверки подлинности имеет значение apiSecretServiceAuth.
composeExtensions.authorization.apiSecretServiceAuthConfiguration.apiSecretRegistrationId Идентификатор регистрации возвращается, когда разработчик отправляет ключ API через портал разработчика.
composeExtensions.apiSpecificationFile Ссылается на файл описания OpenAPI в пакете приложения. Включить, если тип имеет значение apiBased.
composeExtensions.commands.id Уникальный идентификатор, назначенный команде поиска. Запрос пользователя включает этот идентификатор. Идентификатор должен совпадать с OperationId доступным в описании OpenAPI.
composeExtensions.commands.context Массив, в котором определены точки входа для расширения сообщений. Значения по умолчанию: compose и commandBox.
composeExtensions.commands.parameters Определяет статический список параметров для команды . Имя должно сопоставляться с в parameters.name описании OpenAPI. Если вы ссылаетесь на свойство в схеме текста запроса, имя должно сопоставляться с properties.name параметрами запроса или .
composeExtensions.commands.apiResponseRenderingTemplateFile Шаблон, используемый для форматирования ответа JSON из API разработчика в ответ адаптивной карточки. [Обязательно]

Дополнительные сведения см. в разделе ComposeExtensions.


3. Шаблон отрисовки ответа

Примечание.

Teams поддерживает адаптивные карточки до версии 1.5, а адаптивные карточки Designer поддерживают до версии 1.6.

  • Определите URL-адрес ссылки на схему в свойстве $schema , чтобы установить структуру шаблона.
  • Поддерживаемые значения для responseLayoutgridи list , которые определяют способ визуального представления ответа.
  • Рекомендуется jsonPath для массивов или если данные для адаптивной карточки не являются корневым объектом. Например, если данные вложены в productDetails, путь JSON будет иметь значение productDetails.
  • Определите jsonPath в качестве пути к соответствующим данным или массиву в ответе API. Если путь указывает на массив, то каждая запись в массиве привязывается к шаблону адаптивной карточки и возвращается в виде отдельного результата. [Необязательно]
  • Получите пример ответа для проверки шаблона отрисовки ответа. Это служит в качестве теста, чтобы убедиться, что шаблон работает должным образом.
  • Используйте такие средства, как Fiddler или Postman , чтобы вызвать API и убедиться, что запрос и ответ действительны. Этот шаг имеет решающее значение для устранения неполадок и подтверждения правильности работы API.
  • С помощью Designer адаптивной карточки можно привязать ответ API к шаблону отрисовки ответа и просмотреть адаптивную карточку. Вставьте шаблон в РЕДАКТОР ПОЛЕЗНЫХ ДАННЫХ КАРТОЧКИ и вставьте пример записи ответа в РЕДАКТОР ОБРАЗЦОВ ДАННЫХ.

Следующий код является примером шаблона отрисовки ответа:

Пример шаблона отрисовки ответа 
{
"version": "1.0",
"jsonPath": "repairs",
"responseLayout": "grid",
"responseCardTemplate": {
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "ColumnSet",
          "columns": [
            {
              "type": "Column",
              "width": "stretch",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Title: ${if(title, title, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Description: ${if(description, description, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "Image",
                  "url": "${image}",
                  "size": "Medium",
                  "$when": "${image != null}"
                }
              ]
            },
            {
              "type": "Column",
              "width": "auto",
              "items": [
                {
                  "type": "Image",
                  "url": "${if(image, image, '')}",
                  "size": "Medium"
                }
              ]
            }
          ]
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Repair ID:",
              "value": "${if(id, id, 'N/A')}"
            },
            {
              "title": "Date:",
              "value": "${if(date, date, 'N/A')}"
            }
          ]
        }
      ]
    }
  ]
  },
  "previewCardTemplate": {
  "title": "Title: ${if(title, title, 'N/A')}",
  "subtitle": "Description: ${if(description, description, 'N/A')}",
  "text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
  "image": {
    "url": "${image}",
    "$when": "${image != null}"
    }
  }
 }

Карточка предварительного просмотра

Снимок экрана: пример расширения создания, отображающего массив карточек предварительного просмотра при поиске определенного слова. В этом случае при поиске

Расширенная адаптивная карточка

Пример того, как выглядит адаптивная карточка, развернутая после выбора пользователем предварительного карта. На адаптивной карточке отображаются значения Title, Full Description, AssignedTo, RepairId и Date.

Параметры

Свойство Тип Описание Обязательный
version string Версия схемы текущего шаблона отрисовки ответа. Да
jsonPath string Путь к соответствующему разделу в результатах, к которым должны применяться responseCardTemplate и previewCardTemplate. Если значение не задано, корневой объект обрабатывается как соответствующий раздел. Если соответствующий раздел является массивом, каждая запись сопоставляется с responseCardTemplate и previewCardTemplate. Нет
responseLayout responseLayoutType Указывает макет результатов во всплывающем элементе расширения сообщения. Поддерживаемые типы: list и grid. Да
responseCardTemplate adaptiveCardTemplate Шаблон для создания адаптивной карточки из результирующих записей. Да
previewCardTemplate previewCardTemplate Шаблон для создания предварительного карта из записи результата. Результирующий карта предварительного просмотра отображается во всплывающем меню расширения сообщения. Да

Путь JSON

Путь JSON необязателен, но его следует использовать для массивов или где объект, используемый в качестве данных для адаптивного карта, не является корневым объектом. Путь JSON должен соответствовать формату, определенному Newtonsoft. Если путь JSON указывает на массив, то каждая запись в этом массиве привязана к шаблону адаптивного карта и возвращается в виде отдельных результатов.

Примере Предположим, что у вас есть приведенный ниже код JSON для списка продуктов и вы хотите создать карта результат для каждой записи.

{
   "version": "1.0",
   "title": "All Products",
   "warehouse": {
      "products": [
        ...
      ]
   }
}

Как видите, массив результатов находится в разделе "products", который вложен в "warehouse", поэтому путь JSON будет "warehouse.products".

Используйте https://adaptivecards.io/designer/ для предварительного просмотра адаптивной карта, вставив шаблон в полезные данные карточки Редактор, а затем возьмите пример записи ответа из массива или для объекта и вставьте его в редактор данных справа. Убедитесь, что карта правильно отрисовывается и соответствует вашему вкусу. Обратите внимание, что Teams поддерживает карточки до версии 1.5, а конструктор поддерживает 1.6.

Сопоставление схемы

Свойства в документе Описание OpenAPI сопоставляются с шаблоном адаптивной карточки следующим образом:

  • string, number, integerboolean типы преобразуются в TextBlock.

    Примере

    • Исходная схема: string, number, integerи boolean

       name:
   type: string
   example: doggie

    • Целевая схема: Textblock

      {
"type": "TextBlock",
"text": "name: ${if(name, name, 'N/A')}",
"wrap": true
}

  • array: массив преобразуется в контейнер в адаптивной карточке.

    Примере

    • Исходная схема: array

          type: array
              items:
              required:
                - name
              type: object
                properties:
                id:
                  type: integer
                category:
                  type: object
                  properties:
                  name:
                    type: string

    • Целевая схема: Container

          {
              "type": "Container",
              "$data": "${$root}",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "id: ${if(id, id, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "category.name: ${if(category.name, category.name, 'N/A')}",
                  "wrap": true
                }
              ]
            }

  • object: объект преобразуется во вложенное свойство в адаптивной карточке.

    Примере

    • Исходная схема: object

      components:
  schemas:
    Pet:
        category:
          type: object
        properties:
          id:
            type: integer
          name:
            type: string

    • Целевая схема: вложенное свойство в адаптивной карточке

      {
  "type": "TextBlock",
  "text": "category.id: ${if(category.id, category.id, 'N/A')}",
  "wrap": true
},
{
  "type": "TextBlock",
  "text": "category.name: ${if(category.name, category.name, 'N/A')}",
  "wrap": true
}

  • image: если свойство является URL-адресом изображения, оно преобразуется в элемент Image в адаптивной карточке.

    Примере

    • Исходная схема: image

          image:
      type: string
      format: uri
      description: The URL of the image of the item to be repaired

    • Целевая схема: "Image"

      {
      "type": "Image",
      "url": "${image}",
      "$when": "${image != null}"
    }

Проверка подлинности

Вы можете реализовать проверку подлинности в расширениях сообщений на основе API, чтобы обеспечить безопасный и удобный доступ к приложениям. Если для расширения сообщений требуется проверка подлинности, добавьте authorization свойство composeExtensions в манифесте приложения и определите тип проверки подлинности для приложения, задав authType свойство в разделе authorization. Чтобы включить проверку подлинности для расширения сообщений, обновите манифест приложения любым из следующих методов проверки подлинности:

Ни один

Вы можете обновить none как значение для authorization в расширении сообщений на основе API, если расширение сообщений не требует проверки подлинности для пользователя для доступа к API.

    "authorization": {
      "authType": "none"
      }
    },

Проверка подлинности секретной службы

Проверка подлинности секретной службы API — это безопасный метод проверки подлинности приложения с помощью API. Вы можете зарегистрировать ключ API на портале разработчика для Teams и создать идентификатор регистрации ключа API. Обновите манифест приложения с apiSecretServiceAuthConfiguration помощью объекта со свойством apiSecretRegistrationId . Это свойство должно содержать идентификатор ссылки, возвращенный при отправке ключа API через портал.

При инициировании запроса API система получает ключ API из безопасного расположения хранилища и включает его в заголовок авторизации с помощью схемы маркера носителя. Конечная точка API после получения запроса проверяет допустимость ключа API. Если проверка прошла успешно, конечная точка обрабатывает запрос и возвращает нужный ответ, гарантируя, что только запросы, прошедшие проверку подлинности, получают доступ к ресурсам API.

Регистрация ключа API

Регистрация ключа API позволяет защитить свои API, которые находятся за проверкой подлинности и использовать в расширениях сообщений. Вы можете зарегистрировать ключ API и указать домен, клиент и приложение, которые могут получить доступ к API, а также предоставить секреты, необходимые для проверки подлинности вызовов API. Затем можно вставить идентификатор ключа API в упрощенное расширение сообщений, а идентификатор ключа API обеспечивает проверку подлинности для вызовов API, которые находятся за проверкой подлинности.

Чтобы зарегистрировать ключ API, выполните следующие действия.

  1. Перейдите в раздел Сервис>регистрация ключа API.

    Снимок экрана: параметр регистрации ключа API на портале разработчика для Teams.

  2. Выберите + Создать ключ API.

  3. На странице регистрации ключа API в разделе Регистрация ключа API обновите следующее:

    1. Описание: описание ключа API.

    2. Добавить домен: обновите базовый путь для конечных точек API. Путь должен быть защищенным URL-адресом HTTPS, включать полное доменное имя и при необходимости включать определенный путь. Например, https://api.yelp.com.

      Снимок экрана: параметры

  4. В разделе Set a target tenant (Задать целевой клиент) выберите одно из следующих элементов:

    • Главная тетенент
    • Любой клиент
    Вариант Когда использовать Описание
    Домашний клиент При разработке приложения в клиенте и тестировании приложения как пользовательского или пользовательского приложения, созданного для вашей организации. Ключ API можно использовать только в клиенте, где зарегистрирован API.
    Любой клиент После завершения тестирования приложения и включения приложения в разных клиентах. Перед отправкой пакета приложения в Центр партнеров обновите целевой клиент до любого клиента . Ключ API можно использовать в других клиентах после того, как приложение станет доступно в Магазине Teams.

    Снимок экрана: параметры

  5. В разделе Настройка приложения Teams выберите одно из следующих вариантов:

    • Любое приложение Teams
    • Идентификатор существующего приложения Teams
    Вариант Когда использовать Описание
    Любое приложение Teams При разработке приложения в клиенте и тестировании приложения как пользовательского или пользовательского приложения, созданного для вашей организации. Ключ API можно использовать с любым приложением Teams. Это полезно, если после отправки приложения для пользовательского приложения или пользовательского приложения, созданного для вашей организации, создаются идентификаторы.
    Идентификатор существующего приложения Teams После завершения тестирования приложения в клиенте в качестве пользовательского или настраиваемого приложения, созданного для вашей организации. Обновите регистрацию ключа API, выберите Существующее приложение Teams и введите идентификатор манифеста приложения. Параметр Существующее приложение Teams привязывает регистрацию секрета API к конкретному приложению Teams.

    Снимок экрана: параметры любого приложения Teams и Существующее приложение Teams в разделе Настройка заголовка приложения Teams на портале разработчика для Teams.

  6. Выберите + Добавить секрет. Откроется диалоговое окно Добавление ключа API .

  7. Введите значение секрета и нажмите кнопку Сохранить.

    Примечание.

    • Для каждой регистрации ключа API можно хранить до двух секретов. Если один ключ скомпрометирован, его можно быстро удалить и позволит Teams переключиться на второй ключ.
    • Значение секрета должно содержать не менее 10 символов и не более 128 символов.
    • Если первый ключ приводит к ошибке 401, Teams автоматически пытается использовать второй ключ. Это помогает обеспечить непрерывное обслуживание пользователей и устраняет любые потенциальные простои во время создания нового секрета.

    Снимок экрана: параметр Введите значение для этого секрета, чтобы добавить секрет в ключ API.

Создается идентификатор регистрации ключа API .

Снимок экрана: идентификатор регистрации ключа API, созданный на портале разработчика для Teams.

Скопируйте и сохраните идентификатор регистрации ключа API и обновите его как значение свойства apiSecretRegistrationId в манифесте приложения.

Обновление манифеста приложения

Вы можете авторизовать входящие запросы к службе, настроив статический ключ API. Ключ API хранится безопасно и добавляется в вызов API. apiSecretServiceAuthConfiguration Добавьте объект со свойством apiSecretRegistrationId , который содержит идентификатор ссылки при отправке ключа API через портал разработчика для Teams. Дополнительные сведения см. в разделе composeExtensions.commands.

"composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "authorization": {
        "authType": "apiSecretServiceAuth",
        "apiSecretServiceAuthConfiguration": {
            "apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
        }
      },

Microsoft Entra

microsoftEntra Метод проверки подлинности использует удостоверение Teams пользователя приложения, чтобы предоставить ему доступ к приложению. Пользователю, выполнившему вход в Teams, не нужно повторно входить в приложение в среде Teams. Если от пользователя приложения требуется только согласие, приложение Teams получает сведения о доступе для них из Microsoft Entra ID. После того как пользователь приложения дал согласие, он сможет получить доступ к приложению даже с других устройств без необходимости повторной проверки.

Предварительные требования

Перед началом работы убедитесь, что у вас есть следующее:

  • Учетная запись Azure с активной подпиской.
  • Базовое знакомство с разработкой приложений Microsoft Entra ID и Teams.

На следующем рисунке показано, как работает единый вход, когда пользователь приложения Teams пытается получить доступ к приложению расширения сообщений API bsed:

Снимок экрана: как Microsoft Entra авторизация единого входа работает с API проверки подлинности.

  • Пользователь вызывает приложение расширения сообщений на основе API из расширения сообщений в Teams и запрашивает команду, требующую проверки подлинности.
  • Приложение отправляет запрос в серверную службу Teams с идентификатором приложения и необходимым область (access_as_user).
  • Серверная служба Teams проверяет, согласился ли пользователь на приложение и область. Если нет, отображается экран согласия для пользователя и запрашивается разрешение.
  • Если пользователь дает согласие, серверная служба Teams создает маркер доступа для пользователя и приложения и отправляет его приложению в заголовке авторизации запроса.
  • Приложение проверяет маркер. Пользователь может извлечь из маркера сведения о пользователе, такие как имя, адрес электронной почты и идентификатор объекта.
  • Приложение может использовать маркер для вызова собственного API.
  • Приложение возвращает ответ пользователю в Teams.

Чтобы включить microsoftEntra метод проверки подлинности для расширения сообщений на основе API, выполните следующие действия.

Регистрация нового приложения в Microsoft Entra ID

  1. Откройте портал Azure в веб-браузере.

  2. Выберите значок регистрации приложений.

    страница Центр администрирования Microsoft Entra.

    Появится страница регистрации приложений.

  3. Выберите значок + Новая регистрация.

    Новая страница регистрации на Центр администрирования Microsoft Entra.

    Появится страница Регистрация приложения.

  4. Введите имя своего приложения, которое вы хотите отобразить для пользователя приложения. Вы можете изменить имя на более позднем этапе, если захотите.

    Страница регистрации приложения на Центр администрирования Microsoft Entra.

  5. Выберите тип учетной записи пользователя, которая может получить доступ к этому приложению. Вы можете выбрать один или мультитенантный вариант в каталогах организации или ограничить доступ только личными учетными записями Майкрософт.

    Параметры для поддерживаемых типов учетных записей
    Параметр Выберите это, чтобы...
    Только учетные записи в этом каталоге организации (только Майкрософт — один клиент) Создайте приложение для использования только пользователями (или гостями) в вашем клиенте.
    Это приложение, часто называемое пользовательским приложением, созданным для вашей организации (LOB), является приложением с одним клиентом в платформа удостоверений Майкрософт.
    Учетные записи в любом каталоге организации (любой клиент Microsoft Entra ID — мультитенантный клиент) Разрешите пользователям в любом клиенте Microsoft Entra использовать ваше приложение. Этот вариант подходит, например, если вы создаете приложение SaaS и планируете сделать его доступным для нескольких организаций.
    Этот тип приложения называется мультитенантным приложением в платформа удостоверений Майкрософт.
    Учетные записи в любом каталоге организации (любой клиент Microsoft Entra ID — мультитенантный) и личные учетные записи Майкрософт (например, Skype, Xbox) Нацелить на самый широкий круг клиентов.
    Выбрав этот параметр, вы регистрируете мультитенантное приложение, которое может поддерживать пользователей приложений с личными учетными записями Майкрософт.
    Только личные учетные записи Майкрософт Создавайте приложение только для пользователей, у которых есть личные учетные записи Microsoft.

    Примечание.

    Вам не нужно вводить URI перенаправления , чтобы включить единый вход для приложения расширения сообщений на основе API.

  6. Нажмите Зарегистрировать. В браузере появится сообщение о том, что приложение создано.

    Снимок экрана: пример уведомления после успешной регистрации приложения на портал Azure.

    Отобразится страница с идентификатором приложения и другими конфигурациями.

    Снимок экрана: страница сведений о приложении в портал Azure.

  7. Запишите и сохраните идентификатор приложения из идентификатора приложения (клиента), чтобы позже обновить манифест приложения.

    Приложение зарегистрировано в Microsoft Entra ID. Теперь у вас есть идентификатор приложения расширения сообщений на основе API.

Настройка области для маркера доступа

После создания новой регистрации приложения настройте параметры область (разрешения) для отправки маркера доступа в клиент Teams и авторизации доверенных клиентских приложений для включения единого входа.

Чтобы настроить область и авторизовать доверенные клиентские приложения, вам потребуется следующее:

  • Добавление URI идентификатора приложения. Настройте параметры область (разрешения) для приложения. Предоставление веб-API и настройка URI идентификатора приложения.
  • Настройка область API. Определите область для API и пользователей, которые могут дать согласие на область. Вы можете разрешить администраторам предоставлять согласие только для разрешений с более высоким уровнем привилегий.
  • Настройка авторизованного клиентского приложения. Создайте авторизованные идентификаторы клиентов для приложений, которые требуется предварительно авторизовать. Это позволяет пользователю приложения получать доступ к настроенным вами областям приложения (разрешениям) без дополнительного согласия. Предварительная проверка подлинности только тех клиентских приложений, которым вы доверяете, так как пользователи приложения не имеют возможности отклонить согласие.

URI идентификатора приложения.

  1. Выберите Управление>Предоставить API на панели слева.

    Появится страница Предоставление API.

  2. Выберите Добавить , чтобы создать URI идентификатора api://{AppID}приложения в формате .

    Установить URI идентификатора приложения

    Появится раздел для настройки идентификатора приложения URI.

  3. Введите URI идентификатора приложения в формате, описанном здесь.

    URI идентификатора приложения.

    • URI идентификатора приложения заполняется идентификатором приложения (GUID) в формате api://{AppID}.
    • Формат URI идентификатора приложения должен иметь следующий формат: api://fully-qualified-domain-name.com/{AppID}.
    • Вставьте между fully-qualified-domain-name.com и {AppID}api:// (то есть GUID). Например, api://example.com/{AppID}.

    Важно!

    • Конфиденциальные сведения. URI идентификатора приложения регистрируется в процессе проверки подлинности и не должен содержать конфиденциальную информацию.

    • URI идентификатора приложения для приложения с несколькими возможностями. Если вы создаете расширение сообщений на основе API, введите URI идентификатора приложения в качестве api://fully-qualified-domain-name.com/{YourClientId}, где {YourClientId} — это ваш Microsoft Entra идентификатор приложения.

    • Формат доменного имени: используйте строчные буквы для доменного имени. Не используйте верхний регистр.

      Например, чтобы создать службу приложений или веб-приложение с именем ресурса, demoapplicationвыполните :

      Если используется базовое имя ресурса URL-адрес будет... Формат поддерживается на...
      demoapplication https://demoapplication.example.net Все платформы
      DemoApplication https://DemoApplication.example.net Только для компьютеров, Интернета и iOS. Он не поддерживается в Android.

      Используйте вариант demoapplication в нижнем регистре в качестве имени базового ресурса.

  4. Нажмите кнопку Сохранить.

    В браузере появляется всплывающее сообщение о том, что идентификатор URI идентификатора приложения был обновлен.

    URI-сообщение идентификатора приложения

    URI идентификатора приложения отображается на странице.

    URI идентификатора приложения обновлен

  5. Запишите и сохраните URI идентификатора приложения, чтобы позже обновить манифест приложения.

Настройка область API

Примечание.

Расширение сообщений на основе API поддерживает только access_as_user область.

  1. Выберите + Добавить область в разделе Области, определенные этим API.

    Выберите область

    Появится страница Добавление области.

  2. Введите данные для конфигурации области действия.

    На снимке экрана показано, как добавить сведения о область в Azure.

    1. Введите имя области. Это поле является обязательным.
    2. Выберите пользователя, который может дать согласие на эту область. Параметр по умолчанию — Только для администраторов.
    3. Введите отображаемое имя согласия администратора. Это поле является обязательным.
    4. Введите описание для согласия администратора. Это поле является обязательным.
    5. Введите отображаемое имя согласия пользователя.
    6. Введите описание для описания согласия пользователя.
    7. Выберите параметр Включено для состояния.
    8. Нажмите Добавить область.

    В браузере появится сообщение о том, что область добавлена.

    Добавлено сообщение области действия

    Новая область, которую вы определили, отобразится на странице.

    Снимок экрана: пример область добавлен в приложение в портал Azure.

Настройка авторизованного клиентского приложения

  1. Перейдите на страницу Предоставление API в раздел авторизованного клиентского приложения и выберите + Добавить клиентское приложение.

    Авторизованное клиентское приложение

    Появится страница Добавление клиентского приложения.

  2. Введите соответствующий идентификатор клиента Microsoft 365 для приложений, которые вы хотите авторизовать для веб-приложения приложения.

    Снимок экрана: параметр Идентификатор клиента и Авторизованные области для добавления клиентского приложения в приложение в портал Azure. Добавление клиентского приложения

    Примечание.

    • Идентификаторы клиентов Microsoft 365 для мобильных, настольных и веб-приложений для Teams — это фактические идентификаторы, которые необходимо добавить.
    • Для приложения расширения сообщений на основе API Teams требуется веб-приложение или SPA, так как вы не можете использовать мобильное или классическое клиентское приложение в Teams.

    1. Выберите один из следующих идентификаторов клиентов:

      Использовать идентификатор клиента Для авторизации...
      1fec8e78-bce4-4aaf-ab1b-5451cc387264 Мобильное или настольное приложение Teams
      5e3ce6c0-2b1f-4285-8d4b-75ee78787346 Веб-приложение Teams

    2. Выберите URI идентификатора приложения, который вы создали для своего приложения, в Авторизованных областях, чтобы добавить область в предоставленный вами веб-API.

    3. Нажмите кнопку Добавить приложение.

      В браузере появится сообщение о том, что авторизованное клиентское приложение добавлено.

      Добавлено сообщение о добавлении клиентского приложения

      На странице отображается идентификатор клиента авторизованного приложения.

      Приложение клиента добавлено и отображено

Примечание.

Вы можете авторизовать более одного клиентского приложения. Повторите шаги этой процедуры для настройки другого авторизованного клиентского приложения.

Вы успешно настроили область приложений, разрешения и клиентские приложения. Запишите и сохраните универсальный код ресурса (URI) идентификатора приложения. Затем настройте версию маркера доступа.

Обновление манифеста приложения

Примечание.

webApplicationInfo поддерживается в манифесте приложения версии 1.5 или более поздней.

Обновите следующие свойства в файле манифеста приложения:

  • webApplicationInfo: обеспечивает единый вход для приложения, чтобы пользователи приложения могли легко получить доступ к приложению расширения сообщений на основе API. раздел, содержащий важные сведения о вашем приложении. URI идентификатора приложения, зарегистрированный в Microsoft Entra ID, настраивается с помощью область предоставленного API. Настройте URI поддомена приложения в resource , чтобы убедиться, что запрос на проверку подлинности из getAuthToken() домена, указанного в манифесте приложения. Дополнительные сведения см. в webApplicationInfo.

      Снимок экрана: конфигурация манифеста приложения.

  • microsoftEntraConfiguration: включает проверку подлинности единого входа для приложения. supportsSingleSignOn Настройте свойство для для true поддержки единого входа и уменьшения необходимости в нескольких проверках подлинности.

Чтобы настроить манифест приложения, выполните следующие действия.

  1. Откройте проект приложения расширения сообщений на основе API.

  2. Откройте папку манифеста приложения.

    Примечание.

  3. manifest.json Открытие файла

  4. Добавьте следующий фрагмент кода в файл манифеста приложения:

    webApplicationInfo

    "webApplicationInfo":
{
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}

    где

    • {Microsoft Entra AppId}— это идентификатор приложения, созданный при регистрации приложения в Microsoft Entra ID. Это GUID.
    • subdomain.example.com— это URI идентификатора приложения, зарегистрированный при создании область в Microsoft Entra ID.

    MicrosoftEntraConfiguration

    "authorization": {
  "authType": "microsoftEntra",
  “microsoftEntraConfiguration”: {
    “supportsSingleSignOn”: true
  }
},

  5. Обновите URL субдомена в следующих свойствах:

    1. contentUrl
    2. configurationUrl

  6. Сохраните файл манифеста приложения.

Дополнительные сведения см. в разделе composeExtensions.commands.

Маркер проверки подлинности

Когда расширение сообщения вызывает API во время проверки подлинности, оно получает запрос с маркером проверки подлинности пользователя (токеном AED). Затем расширение сообщений добавляет маркер в заголовок авторизации исходящего HTTP-запроса. Формат заголовка — Authorization: Bearer <token_value>. Например, когда расширение сообщений выполняет вызов API к службе, требующей проверки подлинности. Расширение создает HTTP-запрос следующим образом:

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

После того как расширение сообщений на основе API получит заголовок запроса с маркером, выполните следующие действия.

  • Проверка подлинности: проверьте маркер для аудитории, область, издателя и утверждения подписи, чтобы проверка, если маркер предназначен для вашего приложения.

    Ниже приведен пример веб-токена JSON (JWT) с заголовком и ответом:

    {
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "00000002-0000-0000-c000-000000000000",
  "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
  "iat": 1712509315,
  "nbf": 1712509315,
  "exp": 1712513961,
  "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=",
  "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
  "azpacr": "0",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "preferred_username": "john.doe@contoso.com",
  "rh": "I",
  "scp": "access_as_user",
  "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "h7DMQwSPAEeiEe62JJUGAA",
  "ver": "2.0"
  }

  • Использование маркера. Извлеките из маркера сведения о пользователе, такие как имя, адрес электронной почты и идентификатор объекта, и используйте маркер для вызова собственного API приложения расширения сообщений.

    Примечание.

    API получает маркер Microsoft Entra с область, зарегистрированным access_as_user в портал Azure. Однако маркер не авторизован для вызова других подчиненных API, таких как Microsoft Graph.


Устранение неполадок

  • Если при отправке приложения в команды появляется сообщение об ошибке при анализе манифеста , используйте проверяющий элемент приложения Teams для проверки пакета приложения, включая манифест приложения и файл спецификации OpenAPI. Просмотрите манифест приложения и требования к документу OpenAPI Description , чтобы устранить ошибки или предупреждения, и попробуйте отправить приложение.

    Снимок экрана: сообщение об ошибке при отправке приложения в Teams с возможностью копирования сведений об ошибке в буфер обмена.

  • Если при запуске приложения в Teams возникают какие-либо проблемы, выполните следующие действия по устранению неполадок, чтобы определить и устранить проблему.

    • Сеть: выберите вкладку Сеть в Средства разработчика, чтобы проверить активность сети.

      1. Откройте веб-клиент Teams.

      2. Войдите с учетными данными Microsoft 365.

      3. Перейдите в чат и запустите приложение расширения сообщений.

      4. В правом верхнем углу выберите Параметры и прочее (...). Перейдите в раздел Дополнительные инструменты>Средства разработчика.

      5. Выберите пункт Сети. Выберите параметр фильтра и введите invoke в поле поиска.

      6. Выберите ошибку из списка.

      7. В правой области выберите вкладку Ответ .

      8. Отображается объект JSON, представляющий ответ об ошибке от службы или API. Он содержит standardizedError объект с errorCode, errorSubCodeи errorDescription, которые содержат дополнительные сведения об ошибке.

        На снимках экрана показана вкладка

      Распространенные ответы на ошибки HTTP:

      • Ошибка 400 Bad Request может возникнуть, если параметр запроса отсутствует или неправильно отформатирован.
      • Ошибка 401 Unauthorized или 403 Forbidden указывает на проблемы с ключом API, например отсутствие или несанкционированный доступ.
      • Внутренняя ошибка сервера 500 указывает на то, что служба не знает, как реагировать из-за проблемы на стороне сервера.

  • Устранение неполадок с помощью средств. Если информации из трассировки сети недостаточно, можно создать запрос, следуя документу с описанием OpenAPI, и использовать такие средства, как Swagger Редактор или Postman, чтобы протестировать запрос, включая заголовок авторизации для ключа API, если это необходимо.

Если вам не удается устранить ошибки, рекомендуем обратиться в службу поддержки microsoft Teams для получения дополнительной помощи.