Konfigurieren Sie eine Katalogintegration für Amazon API Gateway

Das folgende Diagramm zeigt, wie Snowflake mit Ihrem REST-Katalogserver über API Gateway und SigV4-Authentifizierung interagiert.

Das Diagramm zeigt, wie ein Iceberg REST-Katalog mit Amazon API-Gateway, IAM und S3 funktioniert.

Folgen Sie den Schritten in diesem Thema, um eine REST API im Amazon API Gateway und Signature Version 4 (SigV4) Authentifizierung zu verwenden, um Snowflake sicher mit einem Iceberg-REST-Katalog zu verbinden, der nicht öffentlich zugänglich ist.

  1. Erstellen Sie eine REST API in Amazon API Gateway

  2. Eine IAM-Richtlinie erstellen und mit einer Rolle verknüpfen

  3. API-Gateway-Ressourcenrichtlinie hinzufügen (nur private APIs)

  4. Wählen Sie IAM-basierte Autorisierung für Ihre API aus.

  5. Abrufen der Endpunkt-URL

  6. Katalogintegration für SigV4 erstellen

  7. Vertrauensstellung in IAM konfigurieren

Erstellen Sie eine REST API in Amazon API Gateway

Um Snowflake mit Ihrem Iceberg REST-Katalog zu verbinden, benötigen Sie eine REST API-Ressource in Amazon API Gateway.

Wenn Sie noch keine REST API-Ressource in Amazon API Gateway für Ihren Iceberg-Katalog haben, können Sie eine einfache REST API erstellen, indem Sie eine OpenAPI-Definitionsdatei des Iceberg-Katalogs modifizieren und importieren oder Endpunkte manuell hinzufügen.

Bemerkung

Um die OpenAPI-Definition des Iceberg-Katalogs zu importieren, müssen Sie die YAML-Datei ändern. Amazon API Gateway unterstützt nicht alle Komponenten der OpenAPI 2.0 oder 3.0 Spezifikationen. Unter Amazon API Gateway finden Sie weitere Informationen und wichtige Hinweise für REST APIs.

  1. Suchen Sie in der AWS Management-Konsole nach API Gateway und wählen Sie es aus.

  2. Wählen Sie Create API aus.

  3. Wählen Sie Build unter REST API. Um eine private REST API zu erstellen, wählen Sie Build unter REST API Private.

  4. Wählen Sie eine der folgenden Optionen aus:

    • Um eine API durch manuelles Hinzufügen von Endpunkten zu erstellen, wählen Sie New API.

    • Um eine API unter Verwendung einer OpenAPI-Definitionsdatei zu erstellen, wählen Sie Import API, laden Sie die Datei hoch oder fügen Sie die Definition in den Code-Editor ein.

  5. Geben Sie einen API name und optional eine Description ein.

    Bemerkung

    Sie müssen keine VPC-Endpunkt-ID eingeben, wenn Sie eine private REST API erstellen.

  6. Wählen Sie Create API aus.

Weitere Informationen zum Erstellen und Entwickeln einer REST API in API Gateway finden Sie im Amazon API Gateway Developer Guide.

Eine IAM-Richtlinie erstellen und mit einer Rolle verknüpfen

In diesem Schritt erstellen Sie eine AWS IAM-Rolle, mit der Snowflake eine Verbindung zum API-Gateway herstellen kann. Sie fügen der Rolle eine Richtlinie hinzu, die die Berechtigung zum Aufruf Ihrer API erteilt.

  1. Suchen Sie in der AWS Management-Konsole nach IAM und wählen Sie es aus.

  2. Wählen Sie im linken Navigationsbereich Policies aus.

  3. Wählen Sie Create policy und dann JSON für die Policy editor aus.

  4. Ersetzen Sie die leere Richtlinie durch eine Richtlinie, die die Berechtigung hat, Ihre API-Methoden aufzurufen. Die folgende allgemeine Richtlinie erlaubt beispielsweise die Aktion „Aufrufen“ für alle API Gateway-Ressourcen in einem AWS-Konto.

    {
  "Version": "2012-10-17",
  "Statement": [
    {
        "Effect": "Allow",
        "Action": [
            "execute-api:Invoke"
        ],
        "Resource": "arn:aws:execute-api:*:<aws_account_id>:*"
    }
  ]
}
    Copy

    Wichtig

    Verwenden Sie am besten eine Richtlinie, die die für Ihren Anwendungsfall mindestens erforderlichen Berechtigungen gewährt. Weitere Anleitungen und Beispielrichtlinien finden Sie unter Steuerung des Zugriffs auf eine API mit IAM-Berechtigungen.

  5. Wählen Sie Next aus.

  6. Geben Sie unter Policy name den Namen der Richtlinie (z. B. snowflake_access) und unter Description eine optionale Beschreibung ein.

  7. Wählen Sie Create policy aus.

  8. Wählen Sie im linken Navigationsbereich des IAM-Dashboards die Option Roles.

  9. Wählen Sie eine Rolle aus, der die Richtlinie zugeordnet werden soll. Wenn Sie eine Katalogintegration erstellen, geben Sie diese Rolle an. Wenn Sie keine Rolle haben, erstellen Sie eine neue Rolle.

  10. Wählen Sie auf der Summary Seite „Rolle“ auf der Registerkarte Permissions die Option Add permissions » Attach policies aus.

  11. Suchen Sie nach der Richtlinie, die Sie für API Gateway erstellt haben, und markieren Sie das Kästchen neben der Richtlinie. Wählen Sie dann Add permissions.

  12. Kopieren Sie auf der Seite der Rolle Summary die Rolle ARN. Sie geben diesen ARN an, wenn Sie eine Katalogintegration erstellen.

API-Gateway-Ressourcenrichtlinie hinzufügen (nur private APIs)

Wenn Ihre REST API privat ist, müssen Sie eine Amazon API Gateway-Ressourcenrichtlinie mit Ihrer API verknüpfen. Die Ressourcenrichtlinie ermöglicht es Snowflake, Ihr API von der Amazon Virtual Private Cloud (VPC) aus aufzurufen, in der sich Ihr Snowflake-Konto befindet.

  1. Rufen Sie in Snowflake die Funktion SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO auf, um die IDs für dieVPC abzurufen, in der sich Ihr Snowflake-Konto befindet. Zeichnen Sie über die Funktionsausgabe für jede Eigenschaft, die mit „purpose“: „generic“ identifiziert wurde, die entsprechende(n) VPC-ID auf.

    SELECT SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO();
    Copy

    Ausgabe:

    {
  "snowflake-vpc-id": ["vpc-c1c234a5"],
  "snowflake-egress-vpc-ids": [
    ...
    {
      "id": "vpc-c1c234a5",
      "expires": "2025-03-01T00:00:00",
      "purpose": "generic"
    },
    ...
  ]
}

  2. Folgen Sie den Anweisungen unter Anhängen von API Gateway-Ressourcenrichtlinien, um eine Ressourcenrichtlinie an Ihre REST API anzuhängen.

    Fügen Sie die folgende Beispielrichtlinie ein und ändern Sie sie.

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Deny",
      "Principal": "*",
      "Action": "execute-api:Invoke",
      "Resource": "<api_gateway_arn>",
      "Condition": {
        "StringNotEquals": {
          "aws:sourceVpc": "<snowflake_vpc_id>"
        }
      }
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:sts::123456789XXX:assumed-role/<my_api_permissions_role_name>/snowflake"
      },
      "Action": "execute-api:Invoke",
      "Resource": "<api_gateway_arn>/*/*/*",
      "Condition": {
        "StringEquals": {
          "aws:sourceVpc": "<snowflake_vpc_id>"
        }
      }
    }
  ]
}
    Copy

Die erste Anweisung in der Richtlinie verweigert alle Anfragen, die nicht von Snowflake VPC stammen. Die zweite Anweisung erlaubt die „invoke“-Aktion (für alle Methoden) von Anfragen, die von Snowflake VPC stammen und die angenommene Rolle „Sessionprinzipal“ verwenden.

Weitere Informationen zur API-Gateway-Ressourcenrichtlinie finden Sie unter:

Wählen Sie IAM-basierte Autorisierung für Ihre API aus.

Wählen Sie IAM-basierte Autorisierung für jede Methode, auf die Sie in Ihrem REST API Zugriff gewähren möchten. Mit der IAM-basierten Autorisierung kann Snowflake die von Ihnen konfigurierte IAM -Rolle verwenden, um Anrufe an die API zu tätigen.

  1. Wählen Sie in der Amazon API Gateway-Konsole Ihre REST API.

  2. Für jede Methode:

    1. Wählen Sie unter Resources eine Methode aus der Liste aus.

    2. Wählen Sie unter Method request settings die Option Edit aus.

    3. Wählen Sie unter Authorization die Option AWS IAM aus.

    4. Wählen Sie Save aus.

  3. Um die Autorisierungsänderungen zu übernehmen, wählen Sie Deploy API aus. Weitere Informationen finden Sie unter Bereitstellen einer REST API über die API Gateway-Konsole.

Abrufen der Endpunkt-URL

Rufen Sie Ihren REST API-Endpunkt-URL (oder invoke-URL) ab. Ihre API muss in einem Stagingbereich bereitgestellt werden, bevor Sie die-Endpunkt-URL abrufen können.

  1. Wählen Sie in der Amazon API Gateway-Konsole Ihre REST API.

  2. Wählen Sie im linken Navigationsbereich Stages aus.

  3. Kopieren Sie unter Stage details die Invoke URL.

Sie geben den Endpunkt URL an, wenn Sie eine Katalogintegration erstellen.

Katalogintegration für SigV4 erstellen

Nachdem Sie über eine REST API in Amazon API Gateway verfügen und die ersten Schritte zur Steuerung des Zugriffs auf Ihre API mit IAM-Berechtigungen abgeschlossen haben, können Sie eine Katalogintegration in Snowflake erstellen.

Die Syntax des Befehls und die Beschreibung der Parameter finden Sie unter CREATE CATALOG INTEGRATION (Apache Iceberg™ REST).

Öffentliche REST API

Um eine Katalogintegration für eine öffentliche REST API zu erstellen, geben Sie ICEBERG_REST als CATALOG_SOURCE an und verwenden Sie die Authentifizierung SIGV4.

Geben Sie Details wie Ihre API-Endpunkt-URL und die Ihre IAM-Rollen-ARN an.

CREATE OR REPLACE CATALOG INTEGRATION my_rest_catalog_integration
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://asdlkfjwoalk-execute-api.us-west-2-amazonaws.com/MyApiStage'
    CATALOG_API_TYPE = AWS_API_GATEWAY
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789XXX:role/my_api_permissions_role'
    SIGV4_EXTERNAL_ID = 'my_iceberg_external_id'
  )
  ENABLED = TRUE;
Copy

Private REST API

Um eine Katalogintegration für eine private REST API zu erstellen, müssen Sie den Parameter CATALOG_API_TYPE auf AWS_PRIVATE_API_GATEWAY setzen.

CREATE OR REPLACE CATALOG INTEGRATION my_rest_catalog_integration
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://asdlkfjwoalk-execute-api.us-west-2-amazonaws.com/MyApiStage'
    CATALOG_API_TYPE = AWS_PRIVATE_API_GATEWAY
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789XXX:role/my_api_permissions_role'
    SIGV4_EXTERNAL_ID = 'my_iceberg_external_id'
  )
  ENABLED = TRUE;
Copy

Bemerkung

In beiden Beispielen wird eine externe ID (SIGV4_EXTERNAL_ID = 'my_iceberg_external_id') angegeben, die Sie in der Vertrauensbeziehung für Ihre IAM-Rolle (im nächsten Schritt) verwenden können.

Wenn Sie eine externe ID angeben, können Sie dieselbe IAM-Rolle für mehrere Katalogintegrationen verwenden, ohne die Vertrauensrichtlinie der IAM-Rolle zu aktualisieren. Dies ist besonders in Testszenarien nützlich, wenn Sie eine Katalogintegration mehrmals erstellen oder ersetzen müssen.

Vertrauensstellung in IAM konfigurieren

Rufen Sie Informationen über den Benutzer der AWS IAM ab, der für Ihr Snowflake-Konto erstellt wurde, als Sie die Katalogintegration erstellt haben, und konfigurieren Sie die Vertrauensbeziehung für Ihre IAM-Rolle.

  1. Rufen Sie in Snowflake den Befehl DESCRIBE CATALOG INTEGRATION auf:

    DESCRIBE CATALOG INTEGRATION my_rest_catalog_integration;
    Copy

    Notieren Sie die folgenden Werte:

    Wert

    Beschreibung

    API_AWS_IAM_USER_ARN

    Der AWS-IAM-Benutzer, der für Ihr Snowflake-Konto erstellt wurde, in diesem Beispiel arn:aws:iam::123456789001:user/abc1-b-self1234. Snowflake stellt genau einen IAM-Benutzer für Ihr gesamtes Snowflake-Konto bereit.

    API_AWS_EXTERNAL_ID

    Die externe ID, die notwendig ist, um eine Vertrauensbeziehung aufzubauen. Wenn Sie bei der Erstellung der Katalogintegration keine externe ID (SIGV4_EXTERNAL_ID) angegeben haben, generiert Snowflake eine ID, das Sie verwenden können. Notieren Sie sich den Wert, damit Sie Ihre IAM-Rollen-Vertrauensrichtlinie mit der generierten externen ID aktualisieren können.

  2. Suchen Sie in der AWS Management-Konsole nach IAM und wählen Sie es aus.

  3. Wählen Sie im linken Navigationsbereich Roles aus.

  4. Wählen Sie die IAM-Rolle, die Sie für Ihre Katalogintegration erstellt haben.

  5. Wählen Sie die Registerkarte Trust relationships aus.

  6. Wählen Sie Edit trust policy aus.

  7. Ändern Sie das Richtliniendokument mit den Werten, die Sie aufgezeichnet haben.

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<api_aws_iam_user_arn>"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<api_aws_external_id>"
        }
      }
    }
  ]
}
    Copy

  8. Wählen Sie Update policy aus, um Ihre Änderungen zu speichern.

Sprache: Deutsch