Outils OpenAPI

Un agent peut se connecter à une API externe à l'aide d'un outil OpenAPI en fournissant le schéma OpenAPI. L'agent appellera l'API en votre nom.

Limites :

  • Chaque outil OpenAPI ne peut comporter qu'une seule opération ou fonction.

Exemple de schéma :

openapi: 3.0.0
info:
  title: Simple Pets API
  version: 1.0.0
servers:
  - url: 'https://api.pet-service-example.com/v1'
paths:
  /pets/{petId}:
    get:
      summary: Return a pet by ID.
      operationId: getPet
      parameters:
        - in: path
          name: petId
          required: true
          description: Pet id
          schema:
            type: integer
      responses:
        200:
          description: OK
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      parameters:
        - name: petName
          in: query
          required: false
          description: Pet name
          schema:
            type: string
        - name: label
          in: query
          description: Pet label
          style: form
          explode: true
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-OWNER
          in: header
          description: Optional pet owner provided in the HTTP header
          required: false
          schema:
            type: string
        - name: X-SESSION
          in: header
          description: session id
          required: true
          schema:
            type: string
          x-ces-session-context: $context.session_id
      responses:
        '200':
          description: An array of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        owner:
          type: string
        label:
          type: array
          items:
            type: string

Injecter des variables de contexte de session

Vous pouvez injecter des variables du contexte de session, telles que l'ID de session, dans vos requêtes OpenAPI. Utilisez le champ d'extension x-ces-session-context dans la définition du paramètre. La valeur doit correspondre au chemin d'accès à la variable dans l'objet context.

Exemple :

      parameters:
        - name: X-SESSION
          in: header
          description: session id
          required: true
          schema:
            type: string
          # This extension injects the session ID
          x-ces-session-context: $context.session_id

Points à noter concernant la sécurité

Lorsque vous configurez des outils OpenAPI, il est important de comprendre comment les autorisations sont gérées :

  • Identité d'exécution de l'outil : les actions effectuées par l'outil OpenAPI sont exécutées à l'aide des autorisations accordées au compte de service CX Agent Studio, et non des autorisations directes de l'utilisateur final interagissant avec l'agent.
  • Risque d'accès transitif : cela signifie que si le compte de service CX Agent Studio est autorisé à appeler des fonctions Cloud Run, l'outil peut potentiellement appeler n'importe quelle fonction accessible par ce compte de service, même si l'utilisateur final n'y a pas accès directement.

Pour limiter les risques potentiels associés à ce comportement :

  1. Utilisez des projets dédiés : nous vous recommandons vivement de déployer les applications d'agent dans un projet dédié, distinct des autres ressources critiques ou fonctions sensibles. Cette isolation limite le champ d'application des autorisations disponibles pour le compte de service CX Agent Studio.
  2. Implémentez VPC Service Controls : utilisez VPC Service Controls pour définir un périmètre de service autour de vos services sensibles. Cela vous permet de contrôler l'accès à des services tels que Cloud Run Functions et d'empêcher les appels indésirables du compte de service CX Agent Studio.
  3. Appliquez le principe du moindre privilège : assurez-vous que le compte de service CX Agent Studio ne dispose que des rôles et autorisations Identity and Access Management minimaux nécessaires à son fonctionnement.

Authentification de l'API

Les options d'authentification suivantes sont acceptées lors de l'appel d'une API externe :

Jeton d'ID d'agent de service

CX Agent Studio peut générer un jeton d'identité à l'aide de l'agent de service de la Customer Engagement Suite. Le jeton est ajouté à l'en-tête HTTP d'autorisation lorsque CX Agent Studio appelle une API externe.

Si les fonctions Cloud Run et les services Cloud Run se trouvent dans le même projet que l'agent, vous n'avez pas besoin d'autorisations IAM supplémentaires pour les appeler. S'ils se trouvent dans des projets différents, un jeton d'identité peut être utilisé pour accéder aux fonctions Cloud Run et aux services Cloud Run après avoir attribué les rôles roles/cloudfunctions.invoker et roles/run.invoker à l'adresse de l'agent de service.

Authentification par compte de service

Les comptes de service peuvent être utilisés pour authentifier les requêtes d'outils auprès de toutes les API Google compatibles. Indiquez l'adresse e-mail de votre compte de service.

Si ce n'est pas déjà fait, créez un compte de service.

Comme les comptes de service sont des comptes principaux, ils peuvent accéder aux ressources de votre projet en leur attribuant un rôle, comme vous le feriez pour n'importe quel autre compte principal. L'adresse e-mail du compte de service sera utilisée pour générer un jeton d'accès qui sera envoyé dans l'en-tête Authorization de la requête d'outil.

L'utilisateur qui configure l'outil pour utiliser des comptes de service doit disposer des autorisations suivantes :

  • roles/iam.serviceAccountUser

Pour que Dialogflow CX puisse générer des jetons, l'agent de service Customer Engagement Suite doit disposer des autorisations suivantes :

  • roles/iam.serviceAccountTokenCreator

Le compte de service doit également disposer des autorisations nécessaires pour accéder au service qui héberge l'outil.

OAuth

Fournissez les informations OAuth pour le service que vous utilisez.

Si vous utilisez OAuth pour un service Google, vous devez configurer OAuth pour le service.

Clé API

Vous pouvez configurer l'authentification par clé API en fournissant le nom de la clé, l'emplacement de la requête (en-tête ou chaîne de requête) et la clé API afin que CX Agent Studio transmette la clé API dans la requête. Fournissez votre clé API à l'aide de la version secrète Secret Manager.

Authentification Secret Manager

Vous pouvez stocker les identifiants en tant que secrets à l'aide de Secret Manager. Voici les étapes nécessaires pour authentifier votre outil à l'aide de secrets :

  1. Créez votre secret si vous n'en avez pas encore.
  2. Attribuez le rôle Agent de service Customer Engagement Suite Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) au nouveau secret.
  3. Copiez vos identifiants dans le presse-papiers.
  4. Ajoutez une version de secret à votre secret. Collez vos identifiants en tant que valeur du secret.
    • Omettez tout caractère de nouvelle ligne à la fin.
  5. Copiez le nom de la version du secret que vous venez d'ajouter. Le format du nom est projects/{project_id}/secrets/{secret_id}/versions/{version_id}. Utilisez cette version secrète pour la configuration de l'outil.