SDK für TypeScript mit Streaming verwenden - Schnellstart

1. Zur Verwendung des SDK für TypeScript und JavaScript ist Folgendes erforderlich:

   • Ein Oracle Cloud Infrastructure-Account.
   • Ein in diesem Account erstellter Benutzer in einer Gruppe mit einer Policy, die die erforderlichen Berechtigungen erteilt. Dieser Benutzer kann Ihr eigener Benutzer oder eine andere Person/ein anderes System sein, die/das die API aufrufen muss. Ein Beispiel für die Einrichtung eines neuen Benutzers, einer neuen Gruppe, eines neuen Compartments und einer neuen Policy finden Sie unter Benutzer hinzufügen. Eine Liste der typischen Policys, die Sie verwenden können, finden Sie unter Allgemeine Policys.
   • Ein Schlüsselpaar zum Signieren von API-Anforderungen, wobei der Public Key bei Oracle hochgeladen wird. Nur der Benutzer, der die API aufruft, sollte im Besitz des Private Keys sein. Weitere Informationen finden Sie unter Erste Schritte.
2. Erfassen Sie den Nachrichtenendpunkt und die OCID eines Streams. Die Schritte zum Abrufen von Details für einen Stream finden Sie unter Details für einen Stream abrufen. Im Rahmen dieses Schnellstarts sollte der Stream einen öffentlichen Endpunkt und die von Oracle verwaltete Verschlüsselung verwenden. Informationen hierzu finden Sie unter Streams erstellen und Streampool erstellen, wenn kein Stream vorhanden ist.
3. Node.js-Version 8.x oder höher. Laden Sie die neueste Long-Term-Support-(LTS-)Version herunter.

4. Installieren Sie den TypeScript-Interpreter für NodeJS global:

   npm install -g typescript

5. Visual Code Studio (empfohlen) oder eine andere Integrated Development Environment (IDE).

6. Öffnen Sie eine Befehlszeile mit npm im Pfad, wechseln Sie zum Verzeichnis, in dem Sie den Code für diesen Schnellstart speichern möchten (z.B. wd), und führen Sie dann den folgenden Befehl aus, um das OCI-SDK für TypeScript zu installieren:

   npm install oci-sdk

   Alternativ können Sie effizienter mit Abhängigkeiten arbeiten, indem Sie nur die OCI-TypeScript-SDK-Packages für Authentifizierung und Streaming installieren:

   npm install oci-common
   npm install oci-streaming

7. Stellen Sie sicher, dass Sie über eine gültige SDK-Konfigurationsdatei verfügen. Verwenden Sie für Produktionsumgebungen die Instanz-Principal-Autorisierung.

1. Öffnen Sie Ihren bevorzugten Editor, wie Visual Studio Code, im Verzeichnis wd. oci-sdk-Packages für TypeScript sollten bereits in diesem Verzeichnis installiert sein, nachdem Sie die Schritte unter Voraussetzungen ausgeführt haben.

2. Erstellen Sie eine Datei namens Producer.ts im Verzeichnis wd mit dem folgenden Code. Ersetzen Sie die Werte der Variablen ociConfigFile, ociProfileName,ociStreamOcid und ociMessageEndpointForStream im folgenden Code-Snippet durch die Werte für Ihren Mandanten.

   const common = require("oci-common");
   const st = require("oci-streaming"); // OCI SDK package for OSS
   
   const ociConfigFile = "<config_file_path>";
   const ociProfileName = "<config_file_profile_name>";
   const ociMessageEndpointForStream = "<stream_message_endpoint>"; // example value "https://cell-1.streaming.region.oci.oraclecloud.com"
   const ociStreamOcid = "<stream_OCID>";
   
   // provide authentication for OCI and OSS
   const provider = new common.ConfigFileAuthenticationDetailsProvider(ociConfigFile, ociProfileName);
     
   async function main() {
     // OSS client to produce and consume messages from a Stream in OSS
     const client = new st.StreamClient({ authenticationDetailsProvider: provider });
   
     client.endpoint = ociMessageEndpointForStream;
   
     // build up a putRequest and publish some messages to the stream
     let messages = [];
     for (let i = 1; i <= 3; i++) {
       let entry = {
         key: Buffer.from("messageKey" + i).toString("base64"),
         value: Buffer.from("messageValue" + i).toString("base64")
       };
       messages.push(entry);
     }
   
     console.log("Publishing %s messages to stream %s.", messages.length, ociStreamOcid);
     const putMessageDetails = { messages: messages };
     const putMessagesRequest = {
       putMessagesDetails: putMessageDetails,
       streamId: ociStreamOcid
     };
     const putMessageResponse = await client.putMessages(putMessagesRequest);
     for (var entry of putMessageResponse.putMessagesResult.entries)
       console.log("Published messages to parition %s, offset %s", entry.partition, entry.offset);
   
   }
   
   main().catch((err) => {
     console.log("Error occurred: ", err);
   });
   
   

3. Führen Sie vom Terminal im Verzeichnis wd den folgenden Befehl aus, um Producer.ts zu kompilieren und Producer.js zu generieren:

   tsc Producer.ts

4. Führen Sie in demselben Verzeichnis den folgenden Befehl aus:

   node run Producer.js

   Daraufhin sollte in etwa folgende Terminalausgabe angezeigt werden:

   $:/path/to/directory/wd>node Producer.js
     Publishing 3 messages to stream ocid1.stream.oc1.exampleuniqueID.
     Published messages to parition 0, offset 1314
     Published messages to parition 0, offset 1315
     Published messages to parition 0, offset 1316

5. Zeigen Sie die neuesten Nachrichten an, die an den Stream gesendet wurden, um die neuesten Nachrichten anzuzeigen, die an den Stream gesendet wurden, um zu prüfen, ob die Produktion erfolgreich war.

1. Stellen Sie zunächst sicher, dass der Stream, aus dem Sie Nachrichten konsumieren möchten, Nachrichten enthält. Sie können eine Testnachricht mit der Konsole erstellen oder den Stream und die Nachrichten verwenden, die wir in diesem Schnellstart erstellt haben.
2. Öffnen Sie Ihren bevorzugten Editor, wie Visual Studio Code, im Verzeichnis wd. Die oci-sdk-Packages für TypeScript sollten bereits in diesem Verzeichnis installiert sein, nachdem Sie die Schritte unter Voraussetzungen ausgeführt haben.

3. Erstellen Sie eine Datei namens Consumer.ts im Verzeichnis wd mit dem folgenden Code. Ersetzen Sie die Werte der Variablen ociConfigFile, ociProfileName,ociStreamOcid und ociMessageEndpointForStream im folgenden Code-Snippet durch die Werte für Ihren Mandanten.

   const common = require("oci-common");
   const st = require("oci-streaming"); // OCI SDK package for OSS
   
   const ociConfigFile = "<config_file_path>";
   const ociProfileName = "<config_file_profile_name>";
   const ociMessageEndpointForStream = "<stream_message_endpoint>"; // example value "https://cell-1.streaming.region.oci.oraclecloud.com"
   const ociStreamOcid = "<stream_OCID>";
   
   // provide authentication for OCI and OSS
   const provider = new common.ConfigFileAuthenticationDetailsProvider(ociConfigFile, ociProfileName);
     
   async function main() {
     // OSS client to produce and consume messages from a Stream in OSS
     const client = new st.StreamClient({ authenticationDetailsProvider: provider });
   
     client.endpoint = ociMessageEndpointForStream;
   
     // Use a cursor for getting messages; each getMessages call will return a next-cursor for iteration.
     // There are a couple kinds of cursors, we will use group cursors
   
     // Committed offsets are managed for the group, and partitions
     // are dynamically balanced amongst consumers in the group.
   
     console.log("Starting a simple message loop with a group cursor");
     const groupCursor = await getCursorByGroup(client, ociStreamOcid, "exampleGroup01000", "exampleInstance-1");
     await simpleMessageLoop(client, ociStreamOcid, groupCursor);
   
   }
   
   async function getCursorByGroup(client, streamId, groupName, instanceName) {
       console.log("Creating a cursor for group %s, instance %s.", groupName, instanceName);
       const cursorDetails = {
         groupName: groupName,
         instanceName: instanceName,
         type: st.models.CreateGroupCursorDetails.Type.TrimHorizon,
         commitOnGet: true
       };
       const createCursorRequest = {
         createGroupCursorDetails: cursorDetails,
         streamId: streamId
       };
       const response = await client.createGroupCursor(createCursorRequest);
       return response.cursor.value;
     }
   
   async function simpleMessageLoop(client, streamId, initialCursor) {
       let cursor = initialCursor;
       for (var i = 0; i < 5; i++) {
         const getRequest = {
           streamId: streamId,
           cursor: cursor,
           limit: 100
         };
         const response = await client.getMessages(getRequest);
         console.log("Read %s messages.", response.items.length);
         for (var message of response.items) { 
           if (message.key !== null)  {         
               console.log("Key: %s, Value: %s, Partition: %s",
               Buffer.from(message.key, "base64").toString(),
               Buffer.from(message.value, "base64").toString(),
               Buffer.from(message.partition, "utf8").toString());
           }
          else{
               console.log("Key: Null, Value: %s, Partition: %s",
                   Buffer.from(message.value, "base64").toString(),
                   Buffer.from(message.partition, "utf8").toString());
          }
         }
         
         // getMessages is a throttled method; clients should retrieve sufficiently large message
         // batches, as to avoid too many http requests.
         await delay(2);
         cursor = response.opcNextCursor;
       }
     }
   
     async function delay(s) {
       return new Promise(resolve => setTimeout(resolve, s * 1000));
     }
   
   main().catch((err) => {
       console.log("Error occurred: ", err);
   });
   

4. Führen Sie vom Terminal im Verzeichnis wd den folgenden Befehl aus, um Consumer.ts zu kompilieren und Consumer.js zu generieren:

   tsc Consumer.ts

5. Führen Sie im Verzeichnis wd den folgenden Befehl aus:

   node run Consumer.js

6. Meldungen wie die Folgenden sollten angezeigt werden:

   Starting a simple message loop with a group cursor
   Creating a cursor for group exampleGroup01000, instance exampleInstance-1.
   Read 6 messages.
   Key: messageKey1, Value: messageValue1, Partition: 0
   Key: messageKey2, Value: messageValue2, Partition: 0
   Key: messageKey3, Value: messageValue3, Partition: 0
   Key: Null, Value: message value and key null, Partition: 0
   Key: Null, Value: message value and key null, Partition: 0
   Key: Null, Value: message value and key null, Partition: 0
   Read 0 messages.
   Read 0 messages.
   Read 0 messages.
   Read 0 messages.

   Hinweis
   
   Wenn Sie die Konsole zum Erzeugen einer Testnachricht verwendet haben, lautet der Schlüssel für jede Nachricht Null

Weitere Informationen finden Sie in den folgenden Ressourcen:

1. OCI-SDK für TypeScript auf GitHub
2. Beispiele für OCI-SDK für TypeScript