Help us learn about your current experience with the documentation. Take the survey.

顶级组的审计事件流式传输 GraphQL API

层级：Ultimate
提供：GitLab.com、GitLab 自管版、GitLab 专用版

自定义 HTTP 头 API 在 GitLab 15.1 中引入，附带一个名为 streaming_audit_event_headers 的标志。默认禁用。
自定义 HTTP 头 API 在 GitLab 15.2 中在 GitLab.com 和 GitLab 自管版上启用。
自定义 HTTP 头 API 在 GitLab 15.3 中正式发布。功能标志 streaming_audit_event_headers 已移除。
用户指定的验证令牌 API 支持在 GitLab 15.4 中引入。
功能标志 ff_external_audit_events 在 GitLab 16.2 中默认启用。
用户指定的目标名称 API 支持在 GitLab 16.2 中引入。
API 功能标志 ff_external_audit_events 在 GitLab 16.4 中移除。

使用 GraphQL API 管理顶级组的审计事件流式传输目标。

HTTP 目标

管理顶级组的 HTTP 流式传输目标。

添加新的流式传输目标

向顶级组添加新的流式传输目标。

流式传输目标会接收所有审计事件数据，其中可能包含敏感信息。请确保您信任该流式传输目标。

先决条件：

顶级组的所有者角色。

要启用流式传输并向顶级组添加目标，请使用 externalAuditEventDestinationCreate mutation。

mutation {
  externalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", groupPath: "my-group" } ) {
    errors
    externalAuditEventDestination {
      id
      name
      destinationUrl
      verificationToken
      group {
        name
      }
    }
  }
}

您可以使用 GraphQL externalAuditEventDestinationCreate mutation 选择性地指定您自己的验证令牌（而不是使用 GitLab 生成的默认令牌）。验证令牌长度必须在 16 到 24 个字符之间，末尾的空格不会被修剪。您应该设置一个加密随机且唯一的值。例如：

mutation {
  externalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", groupPath: "my-group", verificationToken: "unique-random-verification-token-here" } ) {
    errors
    externalAuditEventDestination {
      id
      name
      destinationUrl
      verificationToken
      group {
        name
      }
    }
  }
}

您可以使用 GraphQL externalAuditEventDestinationCreate mutation 选择性地指定您自己的目标名称（而不是使用 GitLab 生成的默认名称）。名称长度不得超过 72 个字符，末尾的空格不会被修剪。此值在组范围内应该是唯一的。例如：

mutation {
  externalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", name: "destination-name-here", groupPath: "my-group" }) {
    errors
    externalAuditEventDestination {
      id
      name
      destinationUrl
      verificationToken
      group {
        name
      }
    }
  }
}

如果满足以下条件，则事件流式传输已启用：

返回的 errors 对象为空。
API 响应为 200 OK。

您可以使用 GraphQL auditEventsStreamingHeadersCreate mutation 添加 HTTP 头。您可以通过列出组的所有流式传输目标或从上面的 mutation 中检索目标 ID。

mutation {
  auditEventsStreamingHeadersCreate(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
     key: "foo",
     value: "bar",
     active: false
  }) {
    errors
    header {
      id
      key
      value
      active
    }
  }
}

如果返回的 errors 对象为空，则表示头已创建。

列出流式传输目标

列出顶级组的流式传输目标。

先决条件：

顶级组的所有者角色。

您可以使用 externalAuditEventDestinations 查询类型查看顶级组的流式传输目标列表。

query {
  group(fullPath: "my-group") {
    id
    externalAuditEventDestinations {
      nodes {
        destinationUrl
        verificationToken
        id
        name
        headers {
          nodes {
            key
            value
            id
            active
          }
        }
        eventTypeFilters
        namespaceFilter {
          id
          namespace {
            id
            name
            fullName
          }
        }
      }
    }
  }
}

如果结果列表为空，则表示该组未启用审计流式传输。

更新流式传输目标

更新顶级组的流式传输目标。

先决条件：

顶级组的所有者角色。

要更新组的流式传输目标，请使用 externalAuditEventDestinationUpdate mutation 类型。您可以通过列出组的所有流式传输目标来检索目标 ID。

mutation {
  externalAuditEventDestinationUpdate(input: {
    id:"gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    destinationUrl: "https://www.new-domain.com/webhook",
    name: "destination-name"} ) {
    errors
    externalAuditEventDestination {
      id
      name
      destinationUrl
      verificationToken
      group {
        name
      }
    }
  }
}

如果满足以下条件，则流式传输目标已更新：

返回的 errors 对象为空。
API 响应为 200 OK。

具有组所有者角色的用户可以使用 auditEventsStreamingHeadersUpdate mutation 类型更新流式传输目标的自定义 HTTP 头。您可以通过列出组的所有自定义 HTTP 头来检索自定义 HTTP 头 ID。

mutation {
  auditEventsStreamingHeadersUpdate(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/2", key: "new-key", value: "new-value", active: false }) {
    errors
    header {
      id
      key
      value
      active
    }
  }
}

组所有者可以使用 GraphQL auditEventsStreamingHeadersDestroy mutation 删除 HTTP 头。您可以通过列出组的所有自定义 HTTP 头来检索头 ID。

mutation {
  auditEventsStreamingHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/1" }) {
    errors
  }
}

如果返回的 errors 对象为空，则表示头已删除。

删除流式传输目标

删除顶级组的流式传输目标。

当最后一个目标成功删除时，组的流式传输将被禁用。

先决条件：

顶级组的所有者角色。

具有组所有者角色的用户可以使用 externalAuditEventDestinationDestroy mutation 类型删除流式传输目标。您可以通过列出组的所有流式传输目标来检索目标 ID。

mutation {
  externalAuditEventDestinationDestroy(input: { id: destination }) {
    errors
  }
}

如果满足以下条件，则流式传输目标已删除：

返回的 errors 对象为空。
API 响应为 200 OK。

组所有者可以使用 GraphQL auditEventsStreamingHeadersDestroy mutation 删除 HTTP 头。您可以通过列出组的所有自定义 HTTP 头来检索头 ID。

mutation {
  auditEventsStreamingHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::Header/1" }) {
    errors
  }
}

如果返回的 errors 对象为空，则表示头已删除。

事件类型过滤器

当为组启用此功能时，您可以使用 API 允许用户按目标过滤流式传输的审计事件。如果启用了该功能但没有过滤器，目标将接收所有审计事件。

设置了事件类型过滤器的流式传输目标具有已过滤（）标签。

使用 API 添加事件类型过滤器

先决条件：

您必须具有该组的所有者角色。

您可以使用 auditEventsStreamingDestinationEventsAdd 查询类型添加事件类型过滤器列表：

mutation {
    auditEventsStreamingDestinationEventsAdd(input: {
        destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
        eventTypeFilters: ["list of event type filters"]}){
        errors
        eventTypeFilters
    }
}

如果满足以下条件，则事件类型过滤器已添加：

返回的 errors 对象为空。
API 响应为 200 OK。

使用 API 删除事件类型过滤器

先决条件：

您必须具有该组的所有者角色。

您可以使用 auditEventsStreamingDestinationEventsRemove mutation 类型删除事件类型过滤器列表：

mutation {
    auditEventsStreamingDestinationEventsRemove(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    eventTypeFilters: ["list of event type filters"]
  }){
    errors
  }
}

如果满足以下条件，则事件类型过滤器已删除：

返回的 errors 对象为空。
API 响应为 200 OK。

命名空间过滤器

当您将命名空间过滤器应用于组时，用户可以按目标过滤组的特定子组或项目的流式传输审计事件。否则，目标将接收所有审计事件。

设置了命名空间过滤器的流式传输目标具有已过滤（）标签。

使用 API 添加命名空间过滤器

先决条件：

您必须具有该组的所有者角色。

您可以使用 auditEventsStreamingHttpNamespaceFiltersAdd mutation 类型为子组和项目添加命名空间过滤器。

如果满足以下条件，则命名空间过滤器已添加：

API 返回空的 errors 对象。
API 响应为 200 OK。

子组的 Mutation

mutation auditEventsStreamingHttpNamespaceFiltersAdd {
  auditEventsStreamingHttpNamespaceFiltersAdd(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    groupPath: "path/to/subgroup"
  }) {
    errors
    namespaceFilter {
      id
      namespace {
        id
        name
        fullName
      }
    }
  }
}

项目的 Mutation

mutation auditEventsStreamingHttpNamespaceFiltersAdd {
  auditEventsStreamingHttpNamespaceFiltersAdd(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    projectPath: "path/to/project"
  }) {
    errors
    namespaceFilter {
      id
      namespace {
        id
        name
        fullName
      }
    }
  }
}

使用 API 删除命名空间过滤器

先决条件：

您必须具有该组的所有者角色。

您可以使用 auditEventsStreamingHttpNamespaceFiltersDelete mutation 类型删除命名空间过滤器：

mutation auditEventsStreamingHttpNamespaceFiltersDelete {
  auditEventsStreamingHttpNamespaceFiltersDelete(input: {
    namespaceFilterId: "gid://gitlab/AuditEvents::Streaming::HTTP::NamespaceFilter/5"
  }) {
    errors
  }
}

如果满足以下条件，则命名空间过滤器已删除：

返回的 errors 对象为空。
API 响应为 200 OK。

Google Cloud Logging 目标

管理顶级组的 Google Cloud Logging 目标。

在设置 Google Cloud Logging 流式传输审计事件之前，您必须满足先决条件。

添加新的 Google Cloud Logging 目标

向顶级组添加新的 Google Cloud Logging 配置目标。

先决条件：

顶级组的所有者角色。
具有创建服务帐户和启用 Google Cloud Logging 所需权限的 Google Cloud 项目。

要启用流式传输并添加配置，请使用 GraphQL API 中的 googleCloudLoggingConfigurationCreate mutation。

mutation {
  googleCloudLoggingConfigurationCreate(input: { groupPath: "my-group", googleProjectIdName: "my-google-project", clientEmail: "[email protected]", privateKey: "YOUR_PRIVATE_KEY", logIdName: "audit-events", name: "destination-name" } ) {
    errors
    googleCloudLoggingConfiguration {
      id
      googleProjectIdName
      logIdName
      clientEmail
      name
    }
    errors
  }
}

如果满足以下条件，则事件流式传输已启用：

返回的 errors 对象为空。
API 响应为 200 OK。

列出 Google Cloud Logging 配置

列出顶级组的所有 Google Cloud Logging 配置目标。

先决条件：

顶级组的所有者角色。

您可以使用 googleCloudLoggingConfigurations 查询类型查看顶级组的流式传输配置列表。

query {
  group(fullPath: "my-group") {
    id
    googleCloudLoggingConfigurations {
      nodes {
        id
        logIdName
        googleProjectIdName
        clientEmail
        name
      }
    }
  }
}

如果结果列表为空，则表示该组未启用审计流式传输。

您需要此查询返回的 ID 值用于更新和删除 mutation。

更新 Google Cloud Logging 配置

更新顶级组的 Google Cloud Logging 配置目标。

先决条件：

顶级组的所有者角色。

要更新顶级组的流式传输配置，请使用 googleCloudLoggingConfigurationUpdate mutation 类型。您可以通过列出所有外部目标来检索配置 ID。

mutation {
  googleCloudLoggingConfigurationUpdate(
    input: {id: "gid://gitlab/AuditEvents::GoogleCloudLoggingConfiguration/1", googleProjectIdName: "my-google-project", clientEmail: "[email protected]", privateKey: "YOUR_PRIVATE_KEY", logIdName: "audit-events", name: "updated-destination-name" }
  ) {
    errors
    googleCloudLoggingConfiguration {
      id
      logIdName
      googleProjectIdName
      clientEmail
      name
    }
  }
}

如果满足以下条件，则流式传输配置已更新：

返回的 errors 对象为空。
API 响应为 200 OK。

删除 Google Cloud Logging 配置

删除顶级组的流式传输目标。

当最后一个目标成功删除时，组的流式传输将被禁用。

先决条件：

顶级组的所有者角色。

具有组所有者角色的用户可以使用 googleCloudLoggingConfigurationDestroy mutation 类型删除流式传输配置。您可以通过列出组的所有流式传输目标来检索配置 ID。

mutation {
  googleCloudLoggingConfigurationDestroy(input: { id: "gid://gitlab/AuditEvents::GoogleCloudLoggingConfiguration/1" }) {
    errors
  }
}

如果满足以下条件，则流式传输配置已删除：

返回的 errors 对象为空。
API 响应为 200 OK。