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

实例的审计事件流式传输 GraphQL API

Tier: Ultimate
Offering: GitLab Self-Managed, GitLab Dedicated

在 GitLab 16.0 中引入，附带一个名为 ff_external_audit_events 的功能标志。默认情况下禁用。
实例级别流式传输目标的自定义 HTTP 头 API 在 GitLab 16.1 中引入，附带一个名为 ff_external_audit_events 的功能标志。默认情况下禁用。
功能标志 ff_external_audit_events 在 GitLab 16.2 中默认启用。
用户指定的目标名称 API 支持在 GitLab 16.2 中引入。
实例流式传输目标在 GitLab 16.4 中正式发布。功能标志 ff_external_audit_events 已被移除。

使用 GraphQL API 管理实例的审计事件流式传输目标。

HTTP 目标

管理整个实例的 HTTP 流式传输目标。

添加新的 HTTP 目标

向实例添加新的 HTTP 流式传输目标。

前提条件：

实例的管理员权限。

要启用流式传输并添加目标，请在 GraphQL API 中使用 instanceExternalAuditEventDestinationCreate mutation。

mutation {
  instanceExternalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest"}) {
    errors
    instanceExternalAuditEventDestination {
      destinationUrl
      id
      name
      verificationToken
    }
  }
}

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

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

您可以使用 GraphQL instanceExternalAuditEventDestinationCreate mutation 可选地指定您自己的目标名称（而不是默认的 GitLab 生成的名称）。名称长度不得超过 72 个字符，并且末尾的空格不会被修剪。此值必须是唯一的。例如：

mutation {
  instanceExternalAuditEventDestinationCreate(input: { destinationUrl: "https://mydomain.io/endpoint/ingest", name: "destination-name-here"}) {
    errors
    instanceExternalAuditEventDestination {
      destinationUrl
      id
      name
      verificationToken
    }
  }
}

实例管理员可以使用 GraphQL auditEventsStreamingInstanceHeadersCreate mutation 添加 HTTP 头。您可以通过列出实例的所有流式传输目标或从上一个 mutation 中检索目标 ID。

mutation {
  auditEventsStreamingInstanceHeadersCreate(input:
    {
      destinationId: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/42",
      key: "foo",
      value: "bar",
      active: true
    }) {
    errors
    header {
      id
      key
      value
      active
    }
  }
}

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

列出流式传输目标

列出实例的所有 HTTP 流式传输目标。

前提条件：

实例的管理员权限。

要查看实例的流式传输目标列表，请使用 instanceExternalAuditEventDestinations 查询类型。

query {
  instanceExternalAuditEventDestinations {
    nodes {
      id
      name
      destinationUrl
      verificationToken
      headers {
        nodes {
          id
          key
          value
          active
        }
      }
      eventTypeFilters
    }
  }
}

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

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

更新流式传输目标

更新实例的 HTTP 流式传输目标。

前提条件：

实例的管理员权限。

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

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

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

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

实例管理员可以使用 auditEventsStreamingInstanceHeadersUpdate mutation 类型更新流式传输目标的自定义 HTTP 头。您可以通过列出实例的所有自定义 HTTP 头来检索自定义 HTTP 头 ID。

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

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

删除流式传输目标

删除整个实例的流式传输目标。

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

前提条件：

实例的管理员权限。

要删除流式传输目标，请使用 instanceExternalAuditEventDestinationDestroy mutation 类型。您可以通过列出实例的所有流式传输目标来检索目标 ID。

mutation {
  instanceExternalAuditEventDestinationDestroy(input: { id: "gid://gitlab/AuditEvents::InstanceExternalAuditEventDestination/1" }) {
    errors
  }
}

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

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

要删除 HTTP 头，请使用 GraphQL auditEventsStreamingInstanceHeadersDestroy mutation。要检索头 ID，请列出实例的所有自定义 HTTP 头。

mutation {
  auditEventsStreamingInstanceHeadersDestroy(input: { headerId: "gid://gitlab/AuditEvents::Streaming::InstanceHeader/<id>" }) {
    errors
  }
}

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

事件类型过滤器

当为实例启用此功能时，您可以使用 API 来允许用户按目标筛选流式传输的审计事件。如果启用该功能但未设置任何过滤器，目标将接收所有审计事件。

设置了事件类型过滤器的流式传输目标会带有一个 已过滤 ( ) 标签。

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

前提条件：

您必须拥有实例的管理员权限。

您可以使用 auditEventsStreamingDestinationInstanceEventsAdd mutation 添加事件类型过滤器列表：

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

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

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

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

前提条件：

您必须拥有实例的管理员权限。

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

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

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

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

Google Cloud Logging 目标

管理整个实例的 Google Cloud Logging 目标。

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

添加新的 Google Cloud Logging 目标

向实例添加新的 Google Cloud Logging 配置目标。

前提条件：

您拥有实例的管理员权限。
您拥有一个 Google Cloud 项目，并具有创建服务账户和启用 Google Cloud Logging 的必要权限。

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

mutation {
  instanceGoogleCloudLoggingConfigurationCreate(input: { 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 配置目标。

前提条件：

您拥有实例的管理员权限。

您可以使用 instanceGoogleCloudLoggingConfigurations 查询类型查看实例的流式传输配置列表。

query {
  instanceGoogleCloudLoggingConfigurations {
    nodes {
      id
      logIdName
      googleProjectIdName
      clientEmail
      name
    }
  }
}

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

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

更新 Google Cloud Logging 配置

更新实例的 Google Cloud Logging 配置目标。

前提条件：

您拥有实例的管理员权限。

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

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

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

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

删除 Google Cloud Logging 配置

删除实例的流式传输目标。

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

前提条件：

您拥有实例的管理员权限。

要删除流式传输配置，请使用 instanceGoogleCloudLoggingConfigurationDestroy mutation 类型。您可以通过列出实例的所有流式传输目标来检索配置 ID。

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

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

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