Konfigurieren Sie eine Katalogintegration für Apache Iceberg™ REST-Kataloge¶

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 importieren oder Endpunkte manuell hinzufügen.

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 ID für dieVPC abzurufen, in der sich Ihr Snowflake-Konto befindet. Kopieren Sie die VPC-ID aus der Ausgabe der Funktion.

   SELECT SYSTEM$GET_SNOWFLAKE_PLATFORM_INFO();
   

   Copy

   Ausgabe:

   {"snowflake-vpc-id":["vpc-c1c234a5"]}
   

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::123456789012: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:

• Steuerung des Zugriffs auf eine API mit API –Ressourcenrichtlinien

• API Beispiele für Gateway-Ressourcen-Richtlinien

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'
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my_api_permissions_role'
  )
  ENABLED = TRUE;

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'
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    CATALOG_API_TYPE = AWS_PRIVATE_API_GATEWAY
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my_api_permissions_role'
  )
  ENABLED = TRUE;

Vertrauensstellung in IAM konfigurieren¶

Als Nächstes müssen Sie Informationen zu dem AWS IAM-Benutzer und die externe ID abrufen, die für Ihr Snowflake Konto erstellt wurden, als Sie die Katalogintegration erstellt haben, und die Vertrauensstellung für Ihre IAM-Rolle konfigurieren.

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.

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.