正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

トップレベルグループの監査イベントストリーミングGraphQL API

  • プラン: Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

GraphQL APIを使用して、トップレベルグループの監査イベントストリーミングのストリーミング先を管理します。

HTTPの送信先

トップレベルグループのHTTP監査イベントストリーミングのストリーミング先を管理します。

新しいストリーミング先の追加

トップレベルグループに新しいストリーミング先を追加します。

ストリーミング先は、すべての監査イベントデータを受信します。これには機密情報が含まれる可能性があります。ストリーミング先を信頼できることを確認してください。

前提要件:

  • トップレベルグループのオーナーロール。

監査イベントストリーミングを有効にして、トップレベルグループにストリーミング先を追加するには、externalAuditEventDestinationCreateミューテーションを使用します。

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

オプションで、GraphQL externalAuditEventDestinationCreateミューテーションを使用して、（デフォルトの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ミューテーションを使用して、（デフォルトの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ミューテーションを使用して、HTTPヘッダーを追加できます。ストリーミング先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ミューテーションタイプを使用します。ストリーミング先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ミューテーションタイプを使用して、ストリーミング先のカスタム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ミューテーションを使用してHTTPヘッダーを削除できます。グループのカスタムHTTPヘッダーをすべてリストすることで、ヘッダーIDを取得することができます。

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

返されたerrorsオブジェクトが空の場合、ヘッダーは削除されます。

ストリーミング先を削除する

トップレベルグループのストリーミング先を削除します。

最後のストリーミング先が正常に削除されると、グループのストリーミングは無効になります。

前提要件:

  • トップレベルグループのオーナーロール。

グループのオーナーロールを持つユーザーは、externalAuditEventDestinationDestroyミューテーションタイプを使用して、ストリーミング先を削除できます。ストリーミング先IDは、グループのストリーミング先をすべてリストすることで取得することができます。

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

ストリーミング先が削除されるのは、次の場合です:

  • 返されたerrorsオブジェクトが空です。
  • APIが200 OKで応答します。

グループオーナーは、GraphQL auditEventsStreamingHeadersDestroyミューテーションを使用してHTTPヘッダーを削除できます。グループのカスタムHTTPヘッダーをすべてリストすることで、ヘッダーIDを取得することができます。

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

返されたerrorsオブジェクトが空の場合、ヘッダーは削除されます。

イベントタイプのフィルター

この機能がグループに対して有効になっている場合、APIを使用して、ユーザーがストリーミング先ごとに監査イベントをフィルタリングできるようにすることができます。機能がフィルターなしで有効になっている場合、送信先はすべての監査イベントを受信します。

イベントタイプのフィルターが設定されているストリーミング先には、フィルタリング済み ( filter ) ラベルが付きます。

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 {
    auditEventsStreamingDestinationEventsRemove(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    eventTypeFilters: ["list of event type filters"]
  }){
    errors
  }
}

イベントタイプのフィルターが削除されるのは、次の場合です:

  • 返されたerrorsオブジェクトが空です。
  • APIが200 OKで応答します。

ネームスペースフィルター

ネームスペースフィルターをグループに適用すると、ユーザーは、グループの特定のサブグループまたはプロジェクトのストリーミング先ごとにストリーミングされた監査イベントをフィルタリングできます。それ以外の場合、ストリーミング先はすべての監査イベントを受信します。

ネームスペースフィルターが設定されているストリーミング先には、フィルタリング済み ( filter ) ラベルが付きます。

APIを使用してネームスペースフィルターを追加する

前提要件:

  • グループのオーナーロールを持っている必要があります。

auditEventsStreamingHttpNamespaceFiltersAddミューテーションタイプを使用して、サブグループとプロジェクトの両方に対してネームスペースフィルターを追加できます。

ネームスペースフィルターは、次の条件に該当する場合に追加されます:

  • APIが空のerrorsオブジェクトを返す場合。
  • APIが200 OKで応答します。
サブグループのミューテーション
mutation auditEventsStreamingHttpNamespaceFiltersAdd {
  auditEventsStreamingHttpNamespaceFiltersAdd(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    groupPath: "path/to/subgroup"
  }) {
    errors
    namespaceFilter {
      id
      namespace {
        id
        name
        fullName
      }
    }
  }
}
プロジェクトのミューテーション
mutation auditEventsStreamingHttpNamespaceFiltersAdd {
  auditEventsStreamingHttpNamespaceFiltersAdd(input: {
    destinationId: "gid://gitlab/AuditEvents::ExternalAuditEventDestination/1",
    projectPath: "path/to/project"
  }) {
    errors
    namespaceFilter {
      id
      namespace {
        id
        name
        fullName
      }
    }
  }
}

APIを使用してネームスペースフィルターを削除する

前提要件:

  • グループのオーナーロールを持っている必要があります。

auditEventsStreamingHttpNamespaceFiltersDeleteミューテーションタイプを使用して、ネームスペースフィルターを削除できます:

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 {
  googleCloudLoggingConfigurationCreate(input: { groupPath: "my-group", googleProjectIdName: "my-google-project", clientEmail: "my-email@my-google-project.iam.gservice.account.com", 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値が必要です。

Google Cloud Logging設定を更新する

トップレベルグループのGoogle Cloud Logging設定のストリーミング先を更新します。

前提要件:

  • トップレベルグループのオーナーロール。

トップレベルグループの監査イベントストリーミングの設定を更新するには、googleCloudLoggingConfigurationUpdateミューテーションタイプを使用します。設定IDは、外部のストリーミング先をすべて一覧表示ことで取得することができます。

mutation {
  googleCloudLoggingConfigurationUpdate(
    input: {id: "gid://gitlab/AuditEvents::GoogleCloudLoggingConfiguration/1", googleProjectIdName: "my-google-project", clientEmail: "my-email@my-google-project.iam.gservice.account.com", 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ミューテーションタイプを使用して、監査イベントストリーミングの設定を削除できます。設定IDは、グループのストリーミング先をすべてリストすることで取得することができます。

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

ストリーミングの設定が削除されるのは、次の場合です:

  • 返されたerrorsオブジェクトが空です。
  • APIが200 OKで応答します。